cullmann/cullmann.io
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

use LoveIt theme, self hosted

Browse source
This commit is contained in:
Christoph Cullmann 2021-02-18 21:44:01 +01:00
parent bcafaafff8
commit e9ec93a471
1973 changed files with 54578 additions and 15688 deletions
Download patch file Download diff file Expand all files Collapse all files

BIN
themes/LoveIt/exampleSite/content/posts/theme-documentation-content/featured-image.jpg Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 289 KiB

399
themes/LoveIt/exampleSite/content/posts/theme-documentation-content/index.en.md Normal file
View file

@ -0,0 +1,399 @@
---
weight: 2
title: "Theme Documentation - Content"
date: 2020-03-05T15:58:26+08:00
lastmod: 2020-03-05T15:58:26+08:00
draft: false
author: "Dillon"
authorLink: "https://dillonzq.com"
description: "Find out how to create and organize your content quickly and intuitively in LoveIt theme."
resources:
- name: "featured-image"
src: "featured-image.jpg"
tags: ["content", "Markdown"]
categories: ["documentation"]
lightgallery: true
toc:
auto: false
math:
enable: true
---
Find out how to create and organize your content quickly and intuitively in **LoveIt** theme.
<!--more-->
## 1 Contents Organization {#contents-organization}
A few suggestions to help you get a good looking site quickly:
* Keep post pages in the `content/posts` directory, for example: `content/posts/my-first-post.md`
* Keep other pages in the `content` directory, for example: `content/about.md`
* Local resources organization
{{< admonition note "Local Resource Reference" >}}
{{< version 0.2.10 >}}
There are three ways to reference local resources such as **images** and **music**:
1. Using [page resources](https://gohugo.io/content-management/page-resources/) in [page bundles](https://gohugo.io/content-management/page-bundles/).
You can reference page resources by the value for `Resources.GetMatch` or the filepath of the resource relative to the page directory directly.
2. Store resources in the **assets** directory, which is `/assets` by default.
The filepath of the resource to reference in the post is relative to the assets directory.
3. Store resources in the **static** directory, which is `/static` by default.
The filepath of the resource to reference in the post is relative to the static directory.
The **priority** of references is also in the above order.
There are many places in the theme where the above local resource references can be used,
such as **links**, **images**, `image` shortcode, `music` shortcode and some params in the **front matter**.
Images in page resources or assets directory [processing](https://gohugo.io/content-management/image-processing/)
will be supported in the future.
It's really cool! :(far fa-grin-squint fa-fw):
{{< /admonition >}}
## 2 Front Matter {#front-matter}
**Hugo** allows you to add front matter in `yaml`, `toml` or `json` to your content files.
{{< admonition >}}
**Not all** of the below front matters need to be set in each of your posts.
It is necessary only if the front matters and the `page` part in your [site configuration](../theme-documentation-basics#site-configuration) are inconsistent.
{{< /admonition >}}
Here is a front matter example:
```yaml
---
title: "My First Post"
subtitle: ""
date: 2020-03-04T15:58:26+08:00
lastmod: 2020-03-04T15:58:26+08:00
draft: true
author: ""
authorLink: ""
description: ""
license: ""
images: []
tags: []
categories: []
featuredImage: ""
featuredImagePreview: ""
hiddenFromHomePage: false
hiddenFromSearch: false
twemoji: false
lightgallery: true
ruby: true
fraction: true
fontawesome: true
linkToMarkdown: true
rssFullText: false
toc:
enable: true
auto: true
code:
copy: true
# ...
math:
enable: true
# ...
mapbox:
accessToken: ""
# ...
share:
enable: true
# ...
comment:
enable: true
# ...
library:
css:
# someCSS = "some.css"
# located in "assets/"
# Or
# someCSS = "https://cdn.example.com/some.css"
js:
# someJS = "some.js"
# located in "assets/"
# Or
# someJS = "https://cdn.example.com/some.js"
seo:
images: []
# ...
---
```
* **title**: the title for the content.
* **subtitle**: {{< version 0.2.0 >}} the subtitle for the content.
* **date**: the datetime assigned to this page, which is usually fetched from the `date` field in front matter, but this behaviour is configurabl in the [site configuration](../theme-documentation-basics#site-configuration).
* **lastmod**: the datetime at which the content was last modified.
* **draft**: if `true`, the content will not be rendered unless the `--buildDrafts`/`-D` flag is passed to the `hugo` command.
* **author**: the author for the content.
* **authorLink**: the link of the author.
* **description**: the description for the content.
* **license**: the special lisence for this content.
* **images**: page images for Open Graph and Twitter Cards.
* **tags**: the tags for the content.
* **categories**: the categories for the content.
* **featuredImage**: the featured image for the content.
* **featuredImagePreview**: the featured image for the content preview in the home page.
* **hiddenFromHomePage**: if `true`, the content will not be shown in the home page.
* **hiddenFromSearch**: {{< version 0.2.0 >}} if `true`, the content will not be shown in the search results.
* **twemoji**: {{< version 0.2.0 >}} if `true`, the content will enable the twemoji.
* **lightgallery**: if `true`, images in the content will be shown as the gallery.
* **ruby**: {{< version 0.2.0 >}} if `true`, the content will enable the [ruby extended syntax](#ruby).
* **fraction**: {{< version 0.2.0 >}} if `true`, the content will enable the [fraction extended syntax](#fraction).
* **fontawesome**: {{< version 0.2.0 >}} if `true`, the content will enable the [Font Awesome extended syntax](#fontawesome).
* **linkToMarkdown**: if `true`, the footer of the content will be shown the link to the orignal Markdown file.
* **rssFullText**: {{< version 0.2.4 >}} if `true`, the full text content will be shown in RSS.
* **toc**: {{< version 0.2.9 changed >}} the same as the `params.page.toc` part in the [site configuration](../theme-documentation-basics#site-configuration).
* **code**: {{< version 0.2.0 >}} the same as the `params.page.code` part in the [site configuration](../theme-documentation-basics#site-configuration).
* **math**: {{< version 0.2.0 changed >}} the same as the `params.page.math` part in the [site configuration](../theme-documentation-basics#site-configuration).
* **mapbox**: {{< version 0.2.0 >}} the same as the `params.page.mapbox` part in the [site configuration](../theme-documentation-basics#site-configuration).
* **share**: the same as the `params.page.share` part in the [site configuration](../theme-documentation-basics#site-configuration).
* **comment**: {{< version 0.2.0 changed >}} the same as the `params.page.comment` part in the [site configuration](../theme-documentation-basics#site-configuration).
* **library**: {{< version 0.2.7 >}} the same as the `params.page.library` part in the [site configuration](../theme-documentation-basics#site-configuration).
* **seo**: {{< version 0.2.10 >}} the same as the `params.page.seo` part in the [site configuration](../theme-documentation-basics#site-configuration).
{{< admonition tip >}}
{{< version 0.2.10 >}}
**featuredImage** and **featuredImagePreview** support the complete usage of [local resource references](#contents-organization).
If the page resource with `name: featured-image` or `name: featured-image-preview` is set in the front matter,
it is not necessary to set the parameter `featuredImage` or `featuredImagePreview`:
```yaml
resources:
- name: featured-image
src: featured-image.jpg
- name: featured-image-preview
src: featured-image-preview.jpg
```
{{< /admonition >}}
## 3 Content Summaries
**LoveIt** theme uses the summary of the content to display abstract information in the home page. Hugo can generate summaries of your content.
![Summary Preview](summary.png "Summary Preview")
### Automatic Summary Splitting
By default, Hugo automatically takes the first 70 words of your content as its summary.
You may customize the summary length by setting `summaryLength` in the [site configuration](../theme-documentation-basics#site-configuration).
If you are creating content in a [CJK]^(Chinese/Japanese/Korean) language and want to use Hugo’s automatic summary splitting, set `hasCJKLanguage` to `true` in your [site configuration](../theme-documentation-basics#site-configuration).
### Manual Summary Splitting
Alternatively, you may add the `<!--more-->` summary divider where you want to split the article.
Content that comes before the summary divider will be used as that content’s summary.
{{< admonition >}}
Be careful to enter `<!--more-->` exactly; i.e., all lowercase and with no whitespace.
{{< /admonition >}}
### Front Matter Summary
You might want your summary to be something other than the text that starts the article. In this case you can provide a separate summary in the `summary` variable of the article front matter.
### Use Description as Summary
You might want your description in the `description` variable of the article front matter as the summary.
You may add the `<!--more-->` summary divider at the start of the article. Keep content that comes before the summary divider empty. Then **LoveIt** theme will use your description as the summary.
### Priority Order of Summary Selection
Because there are multiple ways in which a summary can be specified it is useful to understand the order. It is as follows:
1. If there is a `<!--more-->` summary divider present in the article but no content is before the divider, the description will be used as the summary.
2. If there is a `<!--more-->` summary divider present in the article the text up to the divider will be provided as per the manual summary split method.
3. If there is a summary variable in the article front matter the value of the variable will be provided as per the front matter summary method.
4. The text at the start of the article will be provided as per the automatic summary split method.
{{< admonition >}}
It is not recommended to include rich text block elements in the summary, which will cause typographic errors. Such as code blocks, pictures, tables, etc.
{{< /admonition >}}
## 4 Basic Markdown Syntax
This part is shown in the [basic markdown syntax page](../basic-markdown-syntax/).
## 5 Extended Markdown Syntax {#extended-markdown-syntax}
**LoveIt** theme has some extended syntax elements for you to write articles.
### Emoji Support
This part is shown in the [emoji support page](../emoji-support/).
### Mathematical Formula
**LoveIt** theme supports mathematical formulas based on [$ \KaTeX $](https://katex.org/).
Set the property `enable = true` under `[params.math]` in your [site configuration](../theme-documentation-basics#site-configuration)
and the property `math: true` of the article front matter to enable the automatic rendering of mathematical formulas.
{{< admonition tip >}}
Here is a list of [$ \TeX $ functions supported by $ \KaTeX $](https://katex.org/docs/supported.html).
{{< /admonition >}}
#### Block Formula
The default block delimiters are `$$`/`$$` and `\\[`/`\\]`:
```markdown
$$ c = \pm\sqrt{a^2 + b^2} $$
\\[ f(x)=\int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d \xi \\]
```
The rendered output looks like this:
$$ c = \pm\sqrt{a^2 + b^2} $$
\\[ f(x)=\int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d \xi \\]
#### Inline Formula
The default inline delimiters are `$`/`$` and `\\(`/`\\)`:
```markdown
$ c = \pm\sqrt{a^2 + b^2} $ and \\( f(x)=\int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d \xi \\)
```
The rendered output looks like this:
$ c = \pm\sqrt{a^2 + b^2} $ and \\( f(x)=\int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d \xi \\)
{{< admonition tip >}}
You can add more block and inline delimiters in your [site configuration](../theme-documentation-basics#site-configuration).
{{< /admonition >}}
#### Copy-tex
**[Copy-tex](https://github.com/Khan/KaTeX/tree/master/contrib/copy-tex)** is an extension for **$ \KaTeX $**.
By the extension, when selecting and copying $ \KaTeX $ rendered elements, copies their $ \LaTeX $ source to the clipboard.
Set the property `copyTex = true` under `[params.math]` in your [site configuration](../theme-documentation-basics#site-configuration) to enable Copy-tex.
Select and copy the formula rendered in the previous section, and you can find that the copied content is the LaTeX source code.
#### mhchem
**[mhchem](https://github.com/Khan/KaTeX/tree/master/contrib/mhchem)** is an extension for **$ \KaTeX $**.
By the extension, you can write beautiful chemical equations easily in the article.
Set the property `mhchem = true` under `[params.math]` in your [site configuration](../theme-documentation-basics#site-configuration) to enable mhchem.
```markdown
$$ \ce{CO2 + C -> 2 CO} $$
$$ \ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-} $$
```
The rendered output looks like this:
$$ \ce{CO2 + C -> 2 CO} $$
$$ \ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-} $$
### Ruby Annotation {#ruby}
An extended Markdown syntax for **ruby annotation** is supported in **LoveIt** theme:
```markdown
[Hugo]{?^}(An open-source static site generator)
```
The rendered output looks like this:
[Hugo]^(An open-source static site generator)
### Fraction {#fraction}
{{< version 0.2.0 >}}
An extended Markdown syntax for **fraction** is supported in **LoveIt** theme:
```markdown
[Light]{?/}[Dark]
[99]{?/}[100]
```
The rendered output looks like this:
[Light]/[Dark]
[90]/[100]
### Font Awesome {#fontawesome}
**LoveIt** theme uses [Font Awesome](https://fontawesome.com/) as the icon library.
You can easily use these icons in your articles.
Get the `class` of icons you wanted from the [Font Awesome website](https://fontawesome.com/icons?d=gallery).
```markdown
Gone camping! {?:}(fas fa-campground fa-fw): Be back soon.
That is so funny! {?:}(far fa-grin-tears):
```
The rendered output looks like this:
Gone camping! :(fas fa-campground fa-fw): Be back soon.
That is so funny! :(far fa-grin-tears):
### Escape character {#escape-character}
In some special cases (when writing this theme documentation :(far fa-grin-squint-tears):),
your content will conflict with basic or extended Markdown syntax, and it is inevitable.
The escape character syntax can help you build the content you wanted:
```markdown
{{??}X} -> X
```
For example, two `:` will enable emoji syntax, which is not the behavior you want. The escape character syntax is like this:
```markdown
{{??}:}joy:
```
The rendered output looks like this:
**{?:}joy{?:}** instead of **:joy:**
{{< admonition tip >}}
This is related to **[an issue for Hugo](https://github.com/gohugoio/hugo/issues/4978)**, which has not been resolved.
{{< /admonition >}}
Another example is:
```markdown
[link{{??}]}(#escape-character)
```
The rendered output looks like this:
**[link{?]}(#escape-character)** instead of **[link](#escape-character)**.

404
themes/LoveIt/exampleSite/content/posts/theme-documentation-content/index.fr.md Normal file
View file

@ -0,0 +1,404 @@
---
weight: 2
title: "Thème Documentation - Contenu"
date: 2020-03-05T16:30:05+08:00
lastmod: 2020-03-05T16:30:05+08:00
draft: false
author: "Dillon"
authorLink: "https://dillonzq.com"
description: "Découvrez comment créer et organiser votre contenu rapidement et intuitivement dans le thème LoveIt."
resources:
- name: "featured-image"
src: "featured-image.jpg"
tags: ["content", "Markdown"]
categories: ["documentation"]
lightgallery: true
toc:
auto: false
math:
enable: true
---
Découvrez comment créer et organiser votre contenu rapidement et intuitivement dans le thème **LoveIt**.
<!--more-->
{{< admonition warning >}}
Sorry, this article has not been completely translated into **French**.
Welcome to take the time to propose a translation by [:(fas fa-code-branch fa-fw): making a PR](https://github.com/dillonzq/LoveIt/pulls) to the theme!
{{< /admonition >}}
## 1 Contents Organization {#contents-organization}
A few suggestions to help you get a good looking site quickly:
* Keep post pages in the `content/posts` directory, for example: `content/posts/my-first-post.md`
* Keep other pages in the `content` directory, for example: `content/about.md`
* Local resources organization
{{< admonition note "Local Resource Reference" >}}
{{< version 0.2.10 >}}
There are three ways to reference local resources such as **images** and **music**:
1. Using [page resources](https://gohugo.io/content-management/page-resources/) in [page bundles](https://gohugo.io/content-management/page-bundles/).
You can reference page resources by the value for `Resources.GetMatch` or the filepath of the resource relative to the page directory directly.
2. Store resources in the **assets** directory, which is `/assets` by default.
The filepath of the resource to reference in the post is relative to the assets directory.
3. Store resources in the **static** directory, which is `/static` by default.
The filepath of the resource to reference in the post is relative to the static directory.
The **priority** of references is also in the above order.
There are many places in the theme where the above local resource references can be used,
such as **links**, **images**, `image` shortcode, `music` shortcode and some params in the **front matter**.
Images in page resources or assets directory [processing](https://gohugo.io/content-management/image-processing/)
will be supported in the future.
It's really cool! :(far fa-grin-squint fa-fw):
{{< /admonition >}}
## 2 Front Matter {#front-matter}
**Hugo** allows you to add front matter in `yaml`, `toml` or `json` to your content files.
{{< admonition >}}
**Not all** of the below front matters need to be set in each of your posts.
It is necessary only if the front matters and the `page` part in your [site configuration](../theme-documentation-basics#site-configuration) are inconsistent.
{{< /admonition >}}
Here is a front matter example:
```yaml
---
title: "My First Post"
subtitle: ""
date: 2020-03-04T15:58:26+08:00
lastmod: 2020-03-04T15:58:26+08:00
draft: true
author: ""
authorLink: ""
description: ""
license: ""
images: []
tags: []
categories: []
featuredImage: ""
featuredImagePreview: ""
hiddenFromHomePage: false
hiddenFromSearch: false
twemoji: false
lightgallery: true
ruby: true
fraction: true
fontawesome: true
linkToMarkdown: true
rssFullText: false
toc:
enable: true
auto: true
code:
copy: true
# ...
math:
enable: true
# ...
mapbox:
accessToken: ""
# ...
share:
enable: true
# ...
comment:
enable: true
# ...
library:
css:
# someCSS = "some.css"
# located in "assets/"
# Or
# someCSS = "https://cdn.example.com/some.css"
js:
# someJS = "some.js"
# located in "assets/"
# Or
# someJS = "https://cdn.example.com/some.js"
seo:
images: []
# ...
---
```
* **title**: the title for the content.
* **subtitle**: {{< version 0.2.0 >}} the subtitle for the content.
* **date**: the datetime assigned to this page, which is usually fetched from the `date` field in front matter, but this behaviour is configurabl in the [site configuration](../theme-documentation-basics#site-configuration).
* **lastmod**: the datetime at which the content was last modified.
* **draft**: if `true`, the content will not be rendered unless the `--buildDrafts`/`-D` flag is passed to the `hugo` command.
* **author**: the author for the content.
* **authorLink**: the link of the author.
* **description**: the description for the content.
* **license**: the special lisence for this content.
* **images**: page images for Open Graph and Twitter Cards.
* **tags**: the tags for the content.
* **categories**: the categories for the content.
* **featuredImage**: the featured image for the content.
* **featuredImagePreview**: the featured image for the content preview in the home page.
* **hiddenFromHomePage**: if `true`, the content will not be shown in the home page.
* **hiddenFromSearch**: {{< version 0.2.0 >}} if `true`, the content will not be shown in the search results.
* **twemoji**: {{< version 0.2.0 >}} if `true`, the content will enable the twemoji.
* **lightgallery**: if `true`, images in the content will be shown as the gallery.
* **ruby**: {{< version 0.2.0 >}} if `true`, the content will enable the [ruby extended syntax](#ruby).
* **fraction**: {{< version 0.2.0 >}} if `true`, the content will enable the [fraction extended syntax](#fraction).
* **fontawesome**: {{< version 0.2.0 >}} if `true`, the content will enable the [Font Awesome extended syntax](#fontawesome).
* **linkToMarkdown**: if `true`, the footer of the content will be shown the link to the orignal Markdown file.
* **rssFullText**: {{< version 0.2.4 >}} if `true`, the full text content will be shown in RSS.
* **toc**: {{< version 0.2.9 changed >}} the same as the `params.page.toc` part in the [site configuration](../theme-documentation-basics#site-configuration).
* **code**: {{< version 0.2.0 >}} the same as the `params.page.code` part in the [site configuration](../theme-documentation-basics#site-configuration).
* **math**: {{< version 0.2.0 changed >}} the same as the `params.page.math` part in the [site configuration](../theme-documentation-basics#site-configuration).
* **mapbox**: {{< version 0.2.0 >}} the same as the `params.page.mapbox` part in the [site configuration](../theme-documentation-basics#site-configuration).
* **share**: the same as the `params.page.share` part in the [site configuration](../theme-documentation-basics#site-configuration).
* **comment**: {{< version 0.2.0 changed >}} the same as the `params.page.comment` part in the [site configuration](../theme-documentation-basics#site-configuration).
* **library**: {{< version 0.2.7 >}} the same as the `params.page.library` part in the [site configuration](../theme-documentation-basics#site-configuration).
* **seo**: {{< version 0.2.10 >}} the same as the `params.page.seo` part in the [site configuration](../theme-documentation-basics#site-configuration).
{{< admonition tip >}}
{{< version 0.2.10 >}}
**featuredImage** and **featuredImagePreview** support the complete usage of [local resource references](#contents-organization).
If the page resource with `name: featured-image` or `name: featured-image-preview` is set in the front matter,
it is not necessary to set the parameter `featuredImage` or `featuredImagePreview`:
```yaml
resources:
- name: featured-image
src: featured-image.jpg
- name: featured-image-preview
src: featured-image-preview.jpg
```
{{< /admonition >}}
## 3 Content Summaries
**LoveIt** theme uses the summary of the content to display abstract information in the home page. Hugo can generate summaries of your content.
![Summary Preview](summary.png "Summary Preview")
### Automatic Summary Splitting
By default, Hugo automatically takes the first 70 words of your content as its summary.
You may customize the summary length by setting `summaryLength` in the [site configuration](../theme-documentation-basics#site-configuration).
If you are creating content in a [CJK]^(Chinese/Japanese/Korean) language and want to use Hugo’s automatic summary splitting, set `hasCJKLanguage` to `true` in your [site configuration](../theme-documentation-basics#site-configuration).
### Manual Summary Splitting
Alternatively, you may add the `<!--more-->` summary divider where you want to split the article.
Content that comes before the summary divider will be used as that content’s summary.
{{< admonition >}}
Be careful to enter `<!--more-->` exactly; i.e., all lowercase and with no whitespace.
{{< /admonition >}}
### Front Matter Summary
You might want your summary to be something other than the text that starts the article. In this case you can provide a separate summary in the `summary` variable of the article front matter.
### Use Description as Summary
You might want your description in the `description` variable of the article front matter as the summary.
You may add the `<!--more-->` summary divider at the start of the article. Keep content that comes before the summary divider empty. Then **LoveIt** theme will use your description as the summary.
### Priority Order of Summary Selection
Because there are multiple ways in which a summary can be specified it is useful to understand the order. It is as follows:
1. If there is a `<!--more-->` summary divider present in the article but no content is before the divider, the description will be used as the summary.
2. If there is a `<!--more-->` summary divider present in the article the text up to the divider will be provided as per the manual summary split method.
3. If there is a summary variable in the article front matter the value of the variable will be provided as per the front matter summary method.
4. The text at the start of the article will be provided as per the automatic summary split method.
{{< admonition >}}
It is not recommended to include rich text block elements in the summary, which will cause typographic errors. Such as code blocks, pictures, tables, etc.
{{< /admonition >}}
## 4 Basic Markdown Syntax
This part is shown in the [basic markdown syntax page](../basic-markdown-syntax/).
## 5 Extended Markdown Syntax {#extended-markdown-syntax}
**LoveIt** theme has some extended syntax elements for you to write articles.
### Emoji Support
This part is shown in the [emoji support page](../emoji-support/).
### Mathematical Formula
**LoveIt** theme supports mathematical formulas based on [$ \KaTeX $](https://katex.org/).
Set the property `enable = true` under `[params.math]` in your [site configuration](../theme-documentation-basics#site-configuration)
and the property `math: true` of the article front matter to enable the automatic rendering of mathematical formulas.
{{< admonition tip >}}
Here is a list of [$ \TeX $ functions supported by $ \KaTeX $](https://katex.org/docs/supported.html).
{{< /admonition >}}
#### Block Formula
The default block delimiters are `$$`/`$$` and `\\[`/`\\]`:
```markdown
$$ c = \pm\sqrt{a^2 + b^2} $$
\\[ f(x)=\int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d \xi \\]
```
The rendered output looks like this:
$$ c = \pm\sqrt{a^2 + b^2} $$
\\[ f(x)=\int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d \xi \\]
#### Inline Formula
The default inline delimiters are `$`/`$` and `\\(`/`\\)`:
```markdown
$ c = \pm\sqrt{a^2 + b^2} $ and \\( f(x)=\int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d \xi \\)
```
The rendered output looks like this:
$ c = \pm\sqrt{a^2 + b^2} $ and \\( f(x)=\int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d \xi \\)
{{< admonition tip >}}
You can add more block and inline delimiters in your [site configuration](../theme-documentation-basics#site-configuration).
{{< /admonition >}}
#### Copy-tex
**[Copy-tex](https://github.com/Khan/KaTeX/tree/master/contrib/copy-tex)** is an extension for **$ \KaTeX $**.
By the extension, when selecting and copying $ \KaTeX $ rendered elements, copies their $ \LaTeX $ source to the clipboard.
Set the property `copyTex = true` under `[params.math]` in your [site configuration](../theme-documentation-basics#site-configuration) to enable Copy-tex.
Select and copy the formula rendered in the previous section, and you can find that the copied content is the LaTeX source code.
#### mhchem
**[mhchem](https://github.com/Khan/KaTeX/tree/master/contrib/mhchem)** is an extension for **$ \KaTeX $**.
By the extension, you can write beautiful chemical equations easily in the article.
Set the property `mhchem = true` under `[params.math]` in your [site configuration](../theme-documentation-basics#site-configuration) to enable mhchem.
```markdown
$$ \ce{CO2 + C -> 2 CO} $$
$$ \ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-} $$
```
The rendered output looks like this:
$$ \ce{CO2 + C -> 2 CO} $$
$$ \ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-} $$
### Ruby Annotation {#ruby}
An extended Markdown syntax for **ruby annotation** is supported in **LoveIt** theme:
```markdown
[Hugo]{?^}(An open-source static site generator)
```
The rendered output looks like this:
[Hugo]^(An open-source static site generator)
### Fraction {#fraction}
{{< version 0.2.0 >}}
An extended Markdown syntax for **fraction** is supported in **LoveIt** theme:
```markdown
[Light]{?/}[Dark]
[99]{?/}[100]
```
The rendered output looks like this:
[Light]/[Dark]
[90]/[100]
### Font Awesome {#fontawesome}
**LoveIt** theme uses [Font Awesome](https://fontawesome.com/) as the icon library.
You can easily use these icons in your articles.
Get the `class` of icons you wanted from the [Font Awesome website](https://fontawesome.com/icons?d=gallery).
```markdown
Gone camping! {?:}(fas fa-campground fa-fw): Be back soon.
That is so funny! {?:}(far fa-grin-tears):
```
The rendered output looks like this:
Gone camping! :(fas fa-campground fa-fw): Be back soon.
That is so funny! :(far fa-grin-tears):
### Escape character {#escape-character}
In some special cases (when writing this theme documentation :(far fa-grin-squint-tears):),
your content will conflict with basic or extended Markdown syntax, and it is inevitable.
The escape character syntax can help you build the content you wanted:
```markdown
{{??}X} -> X
```
For example, two `:` will enable emoji syntax, which is not the behavior you want. The escape character syntax is like this:
```markdown
{{??}:}joy:
```
The rendered output looks like this:
**{?:}joy{?:}** instead of **:joy:**
{{< admonition tip >}}
This is related to **[an issue for Hugo](https://github.com/gohugoio/hugo/issues/4978)**, which has not been resolved.
{{< /admonition >}}
Another example is:
```markdown
[link{{??}]}(#escape-character)
```
The rendered output looks like this:
**[link{?]}(#escape-character)** instead of **[link](#escape-character)**.

398
themes/LoveIt/exampleSite/content/posts/theme-documentation-content/index.zh-cn.md Normal file
View file

@ -0,0 +1,398 @@
---
weight: 2
title: "主题文档 - 内容"
date: 2020-03-05T16:30:05+08:00
lastmod: 2020-03-05T16:30:05+08:00
draft: false
author: "Dillon"
authorLink: "https://dillonzq.com"
description: "了解如何在 LoveIt 主题中快速, 直观地创建和组织内容."
resources:
- name: "featured-image"
src: "featured-image.jpg"
tags: ["content", "Markdown"]
categories: ["documentation"]
lightgallery: true
toc:
auto: false
math:
enable: true
---
了解如何在 **LoveIt** 主题中快速, 直观地创建和组织内容.
<!--more-->
## 1 内容组织 {#contents-organization}
以下是一些方便你清晰管理和生成文章的目录结构建议:
* 保持博客文章存放在 `content/posts` 目录, 例如: `content/posts/我的第一篇文章.md`
* 保持简单的静态页面存放在 `content` 目录, 例如: `content/about.md`
* 本地资源组织
{{< admonition note "本地资源引用" >}}
{{< version 0.2.10 >}}
有三种方法来引用**图片**和**音乐**等本地资源:
1. 使用[页面包](https://gohugo.io/content-management/page-bundles/)中的[页面资源](https://gohugo.io/content-management/page-resources/).
你可以使用适用于 `Resources.GetMatch` 的值或者直接使用相对于当前页面目录的文件路径来引用页面资源.
2. 将本地资源放在 **assets** 目录中, 默认路径是 `/assets`.
引用资源的文件路径是相对于 assets 目录的.
3. 将本地资源放在 **static** 目录中, 默认路径是 `/static`.
引用资源的文件路径是相对于 static 目录的.
引用的**优先级**符合以上的顺序.
在这个主题中的很多地方可以使用上面的本地资源引用,
例如 **链接**, **图片**, `image` shortcode, `music` shortcode 和**前置参数**中的部分参数.
页面资源或者 **assets** 目录中的[图片处理](https://gohugo.io/content-management/image-processing/)会在未来的版本中得到支持.
非常酷的功能! :(far fa-grin-squint fa-fw):
{{< /admonition >}}
## 2 前置参数 {#front-matter}
**Hugo** 允许你在文章内容前面添加 `yaml`, `toml` 或者 `json` 格式的前置参数.
{{< admonition >}}
**不是所有**的以下前置参数都必须在你的每篇文章中设置.
只有在文章的参数和你的 [网站设置](../theme-documentation-basics#site-configuration) 中的 `page` 部分不一致时才有必要这么做.
{{< /admonition >}}
这是一个前置参数例子:
```yaml
---
title: "我的第一篇文章"
subtitle: ""
date: 2020-03-04T15:58:26+08:00
lastmod: 2020-03-04T15:58:26+08:00
draft: true
author: ""
authorLink: ""
description: ""
license: ""
images: []
tags: []
categories: []
featuredImage: ""
featuredImagePreview: ""
hiddenFromHomePage: false
hiddenFromSearch: false
twemoji: false
lightgallery: true
ruby: true
fraction: true
fontawesome: true
linkToMarkdown: true
rssFullText: false
toc:
enable: true
auto: true
code:
copy: true
# ...
math:
enable: true
# ...
mapbox:
accessToken: ""
# ...
share:
enable: true
# ...
comment:
enable: true
# ...
library:
css:
# someCSS = "some.css"
# 位于 "assets/"
# 或者
# someCSS = "https://cdn.example.com/some.css"
js:
# someJS = "some.js"
# 位于 "assets/"
# 或者
# someJS = "https://cdn.example.com/some.js"
seo:
images: []
# ...
---
```
* **title**: 文章标题.
* **subtitle**: {{< version 0.2.0 >}} 文章副标题.
* **date**: 这篇文章创建的日期时间. 它通常是从文章的前置参数中的 `date` 字段获取的, 但是也可以在 [网站配置](../theme-documentation-basics#site-configuration) 中设置.
* **lastmod**: 上次修改内容的日期时间.
* **draft**: 如果设为 `true`, 除非 `hugo` 命令使用了 `--buildDrafts`/`-D` 参数, 这篇文章不会被渲染.
* **author**: 文章作者.
* **authorLink**: 文章作者的链接.
* **description**: 文章内容的描述.
* **license**: 这篇文章特殊的许可.
* **images**: 页面图片, 用于 Open Graph 和 Twitter Cards.
* **tags**: 文章的标签.
* **categories**: 文章所属的类别.
* **featuredImage**: 文章的特色图片.
* **featuredImagePreview**: 用在主页预览的文章特色图片.
* **hiddenFromHomePage**: 如果设为 `true`, 这篇文章将不会显示在主页上.
* **hiddenFromSearch**: {{< version 0.2.0 >}} 如果设为 `true`, 这篇文章将不会显示在搜索结果中.
* **twemoji**: {{< version 0.2.0 >}} 如果设为 `true`, 这篇文章会使用 twemoji.
* **lightgallery**: 如果设为 `true`, 文章中的图片将可以按照画廊形式呈现.
* **ruby**: {{< version 0.2.0 >}} 如果设为 `true`, 这篇文章会使用 [上标注释扩展语法](#ruby).
* **fraction**: {{< version 0.2.0 >}} 如果设为 `true`, 这篇文章会使用 [分数扩展语法](#fraction).
* **fontawesome**: {{< version 0.2.0 >}} 如果设为 `true`, 这篇文章会使用 [Font Awesome 扩展语法](#fontawesome).
* **linkToMarkdown**: 如果设为 `true`, 内容的页脚将显示指向原始 Markdown 文件的链接.
* **rssFullText**: {{< version 0.2.4 >}} 如果设为 `true`, 在 RSS 中将会显示全文内容.
* **toc**: {{< version 0.2.9 changed >}} 和 [网站配置](../theme-documentation-basics#site-configuration) 中的 `params.page.toc` 部分相同.
* **code**: {{< version 0.2.0 >}} 和 [网站配置](../theme-documentation-basics#site-configuration) 中的 `params.page.code` 部分相同.
* **math**: {{< version 0.2.0 changed >}} 和 [网站配置](../theme-documentation-basics#site-configuration) 中的 `params.page.math` 部分相同.
* **mapbox**: {{< version 0.2.0 >}} 和 [网站配置](../theme-documentation-basics#site-configuration) 中的 `params.page.mapbox` 部分相同.
* **share**: 和 [网站配置](../theme-documentation-basics#site-configuration) 中的 `params.page.share` 部分相同.
* **comment**: {{< version 0.2.0 changed >}} 和 [网站配置](../theme-documentation-basics#site-configuration) 中的 `params.page.comment` 部分相同.
* **library**: {{< version 0.2.7 >}} 和 [网站配置](../theme-documentation-basics#site-configuration) 中的 `params.page.library` 部分相同.
* **seo**: {{< version 0.2.10 >}} 和 [网站配置](../theme-documentation-basics#site-configuration) 中的 `params.page.seo` 部分相同.
{{< admonition tip >}}
{{< version 0.2.10 >}}
**featuredImage** 和 **featuredImagePreview** 支持[本地资源引用](#contents-organization)的完整用法.
如果带有在前置参数中设置了 `name: featured-image` 或 `name: featured-image-preview` 属性的页面资源,
没有必要在设置 `featuredImage` 或 `featuredImagePreview`:
```yaml
resources:
- name: featured-image
src: featured-image.jpg
- name: featured-image-preview
src: featured-image-preview.jpg
```
{{< /admonition >}}
## 3 内容摘要
**LoveIt** 主题使用内容摘要在主页中显示大致文章信息。Hugo 支持生成文章的摘要.
![文章摘要预览](summary.zh-cn.png "文章摘要预览")
### 自动摘要拆分
默认情况下, Hugo 自动将内容的前 70 个单词作为摘要.
你可以通过在 [网站配置](../theme-documentation-basics#site-configuration) 中设置 `summaryLength` 来自定义摘要长度.
如果您要使用 [CJK]^(中文/日语/韩语) 语言创建内容, 并且想使用 Hugo 的自动摘要拆分功能，请在 [网站配置](../theme-documentation-basics#site-configuration) 中将 `hasCJKLanguage` 设置为 `true`.
### 手动摘要拆分
另外, 你也可以添加 `<!--more-->` 摘要分割符来拆分文章生成摘要.
摘要分隔符之前的内容将用作该文章的摘要.
{{< admonition >}}
请小心输入`<!--more-->` ; 即全部为小写且没有空格.
{{< /admonition >}}
### 前置参数摘要
你可能希望摘要不是文章开头的文字. 在这种情况下, 你可以在文章前置参数的 `summary` 变量中设置单独的摘要.
### 使用文章描述作为摘要
你可能希望将文章前置参数中的 `description` 变量的内容作为摘要.
你仍然需要在文章开头添加 `<!--more-->` 摘要分割符. 将摘要分隔符之前的内容保留为空. 然后 **LoveIt** 主题会将你的文章描述作为摘要.
### 摘要选择的优先级顺序
由于可以通过多种方式指定摘要, 因此了解顺序很有用. 如下:
1. 如果文章中有 `<!--more-->` 摘要分隔符, 但分隔符之前没有内容, 则使用描述作为摘要.
2. 如果文章中有 `<!--more-->` 摘要分隔符, 则将按照手动摘要拆分的方法获得摘要.
3. 如果文章前置参数中有摘要变量, 那么将以该值作为摘要.
4. 按照自动摘要拆分方法.
{{< admonition >}}
不建议在摘要内容中包含富文本块元素, 这会导致渲染错误. 例如代码块, 图片, 表格等.
{{< /admonition >}}
## 4 Markdown 基本语法
这部分内容在 [Markdown 基本语法页面](../basic-markdown-syntax/) 中介绍.
## 5 Markdown 扩展语法 {#extended-markdown-syntax}
**LoveIt** 主题提供了一些扩展的语法便于你撰写文章.
### Emoji 支持
这部分内容在 [Emoji 支持页面](../emoji-support/) 中介绍.
### 数学公式
**LoveIt** 基于 [$ \KaTeX $](https://katex.org/) 提供数学公式的支持.
在你的 [网站配置](../theme-documentation-basics#site-configuration) 中的 `[params.math]` 下面设置属性 `enable = true`,
并在文章的前置参数中设置属性 `math: true`来启用数学公式的自动渲染.
{{< admonition tip >}}
有一份 [$ \KaTeX $ 中支持的 $ \TeX $ 函数](https://katex.org/docs/supported.html) 清单.
{{< /admonition >}}
#### 公式块
默认的公式块分割符是 `$$`/`$$` 和 `\\[`/`\\]`:
```markdown
$$ c = \pm\sqrt{a^2 + b^2} $$
\\[ f(x)=\int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d \xi \\]
```
呈现的输出效果如下:
$$ c = \pm\sqrt{a^2 + b^2} $$
\\[ f(x)=\int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d \xi \\]
#### 行内公式
默认的行内公式分割符是 `$`/`$` 和 `\\(`/`\\)`:
```markdown
$ c = \pm\sqrt{a^2 + b^2} $ 和 \\( f(x)=\int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d \xi \\)
```
呈现的输出效果如下:
$ c = \pm\sqrt{a^2 + b^2} $ 和 \\( f(x)=\int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d \xi \\)
{{< admonition tip >}}
你可以在 [网站配置](../theme-documentation-basics#site-configuration) 中自定义公式块和行内公式的分割符.
{{< /admonition >}}
#### Copy-tex
**[Copy-tex](https://github.com/Khan/KaTeX/tree/master/contrib/copy-tex)** 是一个 **$ \KaTeX $** 的插件.
通过这个扩展, 在选择并复制 $ \KaTeX $ 渲染的公式时, 会将其 $ \LaTeX $ 源代码复制到剪贴板.
在你的 [网站配置](../theme-documentation-basics#site-configuration) 中的 `[params.math]` 下面设置属性 `copyTex = true` 来启用 Copy-tex.
选择并复制上一节中渲染的公式, 可以发现复制的内容为 LaTeX 源代码.
#### mhchem
**[mhchem](https://github.com/Khan/KaTeX/tree/master/contrib/mhchem)** 是一个 **$ \KaTeX $** 的插件.
通过这个扩展, 你可以在文章中轻松编写漂亮的化学方程式.
在你的 [网站配置](../theme-documentation-basics#site-configuration) 中的 `[params.math]` 下面设置属性 `mhchem = true` 来启用 mhchem.
```markdown
$$ \ce{CO2 + C -> 2 CO} $$
$$ \ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-} $$
```
呈现的输出效果如下:
$$ \ce{CO2 + C -> 2 CO} $$
$$ \ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-} $$
### 字符注音或者注释 {#ruby}
**LoveIt** 主题支持一种 **字符注音或者注释** Markdown 扩展语法:
```markdown
[Hugo]{?^}(一个开源的静态网站生成工具)
```
呈现的输出效果如下:
[Hugo]^(一个开源的静态网站生成工具)
### 分数 {#fraction}
{{< version 0.2.0 >}}
**LoveIt** 主题支持一种 **分数** Markdown 扩展语法:
```markdown
[浅色]{?/}[深色]
[99]{?/}[100]
```
呈现的输出效果如下:
[浅色]/[深色]
[90]/[100]
### Font Awesome {#fontawesome}
**LoveIt** 主题使用 [Font Awesome](https://fontawesome.com/) 作为图标库.
你同样可以在文章中轻松使用这些图标.
从 [Font Awesome 网站](https://fontawesome.com/icons?d=gallery) 上获取所需的图标 `class`.
```markdown
去露营啦! {?:}(fas fa-campground fa-fw): 很快就回来.
真开心! {?:}(far fa-grin-tears):
```
呈现的输出效果如下:
去露营啦! :(fas fa-campground fa-fw): 很快就回来.
真开心! :(far fa-grin-tears):
### 转义字符 {#escape-character}
在某些特殊情况下 (编写这个主题文档时 :(far fa-grin-squint-tears):),
你的文章内容会与 Markdown 的基本或者扩展语法冲突, 并且无法避免.
转义字符语法可以帮助你渲染出想要的内容:
```markdown
{{??}X} -> X
```
例如, 两个 `:` 会启用 emoji 语法. 但有时候这不是你想要的结果. 可以像这样使用转义字符语法:
```markdown
{{??}:}joy:
```
呈现的输出效果如下:
**{?:}joy{?:}** 而不是 **:joy:**
{{< admonition tip >}}
这个方法可以间接解决一个还未解决的 **[Hugo 的 issue](https://github.com/gohugoio/hugo/issues/4978)**.
{{< /admonition >}}
另一个例子是:
```markdown
[link{{??}]}(#escape-character)
```
呈现的输出效果如下:
**[link{?]}(#escape-character)** 而不是 **[link](#escape-character)**.

BIN
themes/LoveIt/exampleSite/content/posts/theme-documentation-content/summary.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 272 KiB

BIN
themes/LoveIt/exampleSite/content/posts/theme-documentation-content/summary.zh-cn.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 269 KiB