mirror of
https://github.com/idanoo/m2.nz.git
synced 2024-11-30 04:05:13 +00:00
519 lines
17 KiB
Markdown
519 lines
17 KiB
Markdown
---
|
||
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: []
|
||
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
|
||
maxShownLines: 50
|
||
math:
|
||
enable: false
|
||
# ...
|
||
mapbox:
|
||
# ...
|
||
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.
|
||
|
||
|
||
|
||
### 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
|
||
|
||
{{< version 0.2.11 changed >}}
|
||
|
||
**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](../theme-documentation-extended-shortcodes#12-raw) 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)**.
|