idanoo/m2.nz
1
0
Fork 0
mirror of https://github.com/idanoo/m2.nz.git synced 2024-11-30 12:13:08 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
gitea_woodpecker
m2.nz/themes/LoveIt/exampleSite/content/posts/theme-documentation-content/index.en.md

516 lines
17 KiB
Markdown
Raw Permalink Normal View History

Add theme
2022-05-08 06:47:31 +00:00
---
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."
images: ["featured-image.png"]
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.
**$\KaTeX$** automatically renders formulas based on **specific delimiters**.
{{< admonition tip >}}
Here is a list of [$\TeX$ functions supported by $\KaTeX$](https://katex.org/docs/supported.html).
{{< /admonition >}}
{{< admonition >}}
Since Hugo generates HTML documents according to the syntax such as `_`/`*`/`>>` when rendering Markdown documents,
and some text content in the form of escape characters
(such as `\(`/`\)`/`\[`/`\]`/`\\`) escape processing will be performed automatically,
therefore, additional escape character expressions are required for these places to achieve automatic rendering:
* `_` -> `\_`
* `*` -> `\*`
* `>>` -> `\>>`
* `\(` -> `\\(`
* `\)` -> `\\)`
* `\[` -> `\\[`
* `\]` -> `\\]`
* `\\` -> `\\\\`
**LoveIt** theme supports `raw` shortcode to avoid these escape characters,
which helps you write raw mathematical formula content.
Example `raw` input:
```markdown
Inline Formula: {{</* raw */>}}\(\mathbf{E}=\sum_{i} \mathbf{E}_{i}=\mathbf{E}_{1}+\mathbf{E}_{2}+\mathbf{E}_{3}+\cdots\){{</* /raw */>}}
Block Formula:
{{</* raw */>}}
\[ a=b+c \\ d+e=f \]
{{</* /raw */>}}
```
The rendered output looks like this:
Inline Formula: {{< raw >}}\(\mathbf{E}=\sum_{i} \mathbf{E}_{i}=\mathbf{E}_{1}+\mathbf{E}_{2}+\mathbf{E}_{3}+\cdots\){{< /raw >}}
Block Formula:
{{< raw>}}
\[ a=b+c \\ d+e=f \]
{{< /raw >}}
{{< /admonition >}}
#### Inline Formula
The default inline delimiters are:
* `$ ... $`
* `\( ... \)` (escaped: `\\( ... \\)`)
For example:
```tex
$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\\)
#### Block Formula
The default block delimiters are:
* `$$ ... $$`
* `\[ ... \]` (escaped: `\\[ ... \\]`)
* `\begin{equation} ... \end{equation}` (unnumbered: `\begin{equation*} ... \end{equation*}`)
* `\begin{align} ... \end{align}` (unnumbered: `\begin{align*} ... \end{align*}`)
* `\begin{alignat} ... \end{alignat}` (unnumbered: `\begin{alignat*} ... \end{alignat*}`)
* `\begin{gather} ... \end{gather}` (unnumbered: `\begin{gather*} ... \end{gather*}`)
* `\begin{CD} ... \end{CD}`
For example:
```tex
$$ c = \pm\sqrt{a^2 + b^2} $$
\\[ f(x)=\int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d \xi \\]
\begin{equation*}
\rho \frac{\mathrm{D} \mathbf{v}}{\mathrm{D} t}=\nabla \cdot \mathbb{P}+\rho \mathbf{f}
\end{equation*}
\begin{equation}
\mathbf{E}=\sum_{i} \mathbf{E}\_{i}=\mathbf{E}\_{1}+\mathbf{E}\_{2}+\mathbf{E}_{3}+\cdots
\end{equation}
\begin{align}
a&=b+c \\\\
d+e&=f
\end{align}
\begin{alignat}{2}
10&x+&3&y = 2 \\\\
3&x+&13&y = 4
\end{alignat}
\begin{gather}
a=b \\\\
e=b+c
\end{gather}
\begin{CD}
A @>a\>> B \\\\
@VbVV @AAcA \\\\
C @= D
\end{CD}
```
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 \\]
\begin{equation*}
\rho \frac{\mathrm{D} \mathbf{v}}{\mathrm{D} t}=\nabla \cdot \mathbb{P}+\rho \mathbf{f}
\end{equation*}
\begin{equation}
\mathbf{E}=\sum_{i} \mathbf{E}\_{i}=\mathbf{E}\_{1}+\mathbf{E}\_{2}+\mathbf{E}_{3}+\cdots
\end{equation}
\begin{align}
a&=b+c \\\\
d+e&=f
\end{align}
\begin{alignat}{2}
10&x+&3&y = 2 \\\\
3&x+&13&y = 4
\end{alignat}
\begin{gather}
a=b \\\\
e=b+c
\end{gather}
\begin{CD}
A @>a\>> B \\\\
@VbVV @AAcA \\\\
C @= D
\end{CD}
{{< admonition tip >}}
You can add more inline and block 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)**.
Reference in New Issue Copy Permalink