diff options
Diffstat (limited to 'themes/CodeIT/exampleSite/content/posts/theme-documentation-content')
| -rw-r--r-- | themes/CodeIT/exampleSite/content/posts/theme-documentation-content/featured-image.jpg | bin | 0 -> 296383 bytes | |||
| -rw-r--r-- | themes/CodeIT/exampleSite/content/posts/theme-documentation-content/index.en.md | 397 | ||||
| -rw-r--r-- | themes/CodeIT/exampleSite/content/posts/theme-documentation-content/index.fr.md | 402 | ||||
| -rw-r--r-- | themes/CodeIT/exampleSite/content/posts/theme-documentation-content/index.zh-cn.md | 396 | ||||
| -rw-r--r-- | themes/CodeIT/exampleSite/content/posts/theme-documentation-content/summary.png | bin | 0 -> 278993 bytes | |||
| -rw-r--r-- | themes/CodeIT/exampleSite/content/posts/theme-documentation-content/summary.zh-cn.png | bin | 0 -> 275314 bytes |
6 files changed, 1195 insertions, 0 deletions
diff --git a/themes/CodeIT/exampleSite/content/posts/theme-documentation-content/featured-image.jpg b/themes/CodeIT/exampleSite/content/posts/theme-documentation-content/featured-image.jpg Binary files differnew file mode 100644 index 0000000..102e184 --- /dev/null +++ b/themes/CodeIT/exampleSite/content/posts/theme-documentation-content/featured-image.jpg diff --git a/themes/CodeIT/exampleSite/content/posts/theme-documentation-content/index.en.md b/themes/CodeIT/exampleSite/content/posts/theme-documentation-content/index.en.md new file mode 100644 index 0000000..12bfd45 --- /dev/null +++ b/themes/CodeIT/exampleSite/content/posts/theme-documentation-content/index.en.md @@ -0,0 +1,397 @@ +--- +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: "Sunt Programator!" +authorLink: "https://suntprogramator.dev/" +description: "Find out how to create and organize your content quickly and intuitively in CodeIT 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 **CodeIT** 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" >}} + +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**: 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**: if `true`, the content will not be shown in the search results. +- **twemoji**: if `true`, the content will enable the twemoji. +- **lightgallery**: if `true`, images in the content will be shown as the gallery. +- **ruby**: if `true`, the content will enable the [ruby extended syntax](#ruby). +- **fraction**: if `true`, the content will enable the [fraction extended syntax](#fraction). +- **fontawesome**: 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**: if `true`, the full text content will be shown in RSS. + +- **toc**: the same as the `params.page.toc` part in the [site configuration](../theme-documentation-basics#site-configuration). +- **code**: the same as the `params.page.code` part in the [site configuration](../theme-documentation-basics#site-configuration). +- **math**: the same as the `params.page.math` part in the [site configuration](../theme-documentation-basics#site-configuration). +- **mapbox**: 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**: the same as the `params.page.comment` part in the [site configuration](../theme-documentation-basics#site-configuration). +- **library**: the same as the `params.page.library` part in the [site configuration](../theme-documentation-basics#site-configuration). +- **seo**: the same as the `params.page.seo` part in the [site configuration](../theme-documentation-basics#site-configuration). + +{{< admonition tip >}} + +**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 + +**CodeIT** 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 **CodeIT** 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} + +**CodeIT** 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 + +**CodeIT** 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 **CodeIT** theme: + +```markdown +[Hugo]{?^}(An open-source static site generator) +``` + +The rendered output looks like this: + +[Hugo]^(An open-source static site generator) + +### Fraction {#fraction} + +An extended Markdown syntax for **fraction** is supported in **CodeIT** theme: + +```markdown +[Light]{?/}[Dark] + +[99]{?/}[100] +``` + +The rendered output looks like this: + +[Light]/[Dark] + +[90]/[100] + +### Font Awesome {#fontawesome} + +**CodeIT** 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)**. diff --git a/themes/CodeIT/exampleSite/content/posts/theme-documentation-content/index.fr.md b/themes/CodeIT/exampleSite/content/posts/theme-documentation-content/index.fr.md new file mode 100644 index 0000000..4283c63 --- /dev/null +++ b/themes/CodeIT/exampleSite/content/posts/theme-documentation-content/index.fr.md @@ -0,0 +1,402 @@ +--- +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: "Sunt Programator!" +authorLink: "https://suntprogramator.dev/" +description: "Découvrez comment créer et organiser votre contenu rapidement et intuitivement dans le thème CodeIT." +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 **CodeIT**. + +<!--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/sunt-programator/CodeIT/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" >}} + +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**: 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**: if `true`, the content will not be shown in the search results. +- **twemoji**: if `true`, the content will enable the twemoji. +- **lightgallery**: if `true`, images in the content will be shown as the gallery. +- **ruby**: if `true`, the content will enable the [ruby extended syntax](#ruby). +- **fraction**: if `true`, the content will enable the [fraction extended syntax](#fraction). +- **fontawesome**: 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**: if `true`, the full text content will be shown in RSS. + +- **toc**: the same as the `params.page.toc` part in the [site configuration](../theme-documentation-basics#site-configuration). +- **code**: the same as the `params.page.code` part in the [site configuration](../theme-documentation-basics#site-configuration). +- **math**: the same as the `params.page.math` part in the [site configuration](../theme-documentation-basics#site-configuration). +- **mapbox**: 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**: the same as the `params.page.comment` part in the [site configuration](../theme-documentation-basics#site-configuration). +- **library**: the same as the `params.page.library` part in the [site configuration](../theme-documentation-basics#site-configuration). +- **seo**: the same as the `params.page.seo` part in the [site configuration](../theme-documentation-basics#site-configuration). + +{{< admonition tip >}} + +**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 + +**CodeIT** 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 **CodeIT** 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} + +**CodeIT** 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 + +**CodeIT** 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 **CodeIT** theme: + +```markdown +[Hugo]{?^}(An open-source static site generator) +``` + +The rendered output looks like this: + +[Hugo]^(An open-source static site generator) + +### Fraction {#fraction} + +An extended Markdown syntax for **fraction** is supported in **CodeIT** theme: + +```markdown +[Light]{?/}[Dark] + +[99]{?/}[100] +``` + +The rendered output looks like this: + +[Light]/[Dark] + +[90]/[100] + +### Font Awesome {#fontawesome} + +**CodeIT** 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)**. diff --git a/themes/CodeIT/exampleSite/content/posts/theme-documentation-content/index.zh-cn.md b/themes/CodeIT/exampleSite/content/posts/theme-documentation-content/index.zh-cn.md new file mode 100644 index 0000000..7fe0dc7 --- /dev/null +++ b/themes/CodeIT/exampleSite/content/posts/theme-documentation-content/index.zh-cn.md @@ -0,0 +1,396 @@ +--- +weight: 2 +title: "主题文档 - 内容" +date: 2020-03-05T16:30:05+08:00 +lastmod: 2020-03-05T16:30:05+08:00 +draft: false +author: "Sunt Programator!" +authorLink: "https://suntprogramator.dev/" +description: "了解如何在 CodeIT 主题中快速, 直观地创建和组织内容." +resources: + - name: "featured-image" + src: "featured-image.jpg" + +tags: ["content", "Markdown"] +categories: ["documentation"] + +lightgallery: true + +toc: + auto: false +math: + enable: true +--- + +了解如何在 **CodeIT** 主题中快速, 直观地创建和组织内容. + +<!--more--> + +## 1 内容组织 {#contents-organization} + +以下是一些方便你清晰管理和生成文章的目录结构建议: + +- 保持博客文章存放在 `content/posts` 目录, 例如: `content/posts/我的第一篇文章.md` +- 保持简单的静态页面存放在 `content` 目录, 例如: `content/about.md` +- 本地资源组织 + +{{< admonition note "本地资源引用" >}} + +有三种方法来引用**图片**和**音乐**等本地资源: + +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**: 文章副标题. +- **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**: 如果设为 `true`, 这篇文章将不会显示在搜索结果中. +- **twemoji**: 如果设为 `true`, 这篇文章会使用 twemoji. +- **lightgallery**: 如果设为 `true`, 文章中的图片将可以按照画廊形式呈现. +- **ruby**: 如果设为 `true`, 这篇文章会使用 [上标注释扩展语法](#ruby). +- **fraction**: 如果设为 `true`, 这篇文章会使用 [分数扩展语法](#fraction). +- **fontawesome**: 如果设为 `true`, 这篇文章会使用 [Font Awesome 扩展语法](#fontawesome). +- **linkToMarkdown**: 如果设为 `true`, 内容的页脚将显示指向原始 Markdown 文件的链接. +- **rssFullText**: 如果设为 `true`, 在 RSS 中将会显示全文内容. + +- **toc**: 和 [网站配置](../theme-documentation-basics#site-configuration) 中的 `params.page.toc` 部分相同. +- **code**: 和 [网站配置](../theme-documentation-basics#site-configuration) 中的 `params.page.code` 部分相同. +- **math**: 和 [网站配置](../theme-documentation-basics#site-configuration) 中的 `params.page.math` 部分相同. +- **mapbox**: 和 [网站配置](../theme-documentation-basics#site-configuration) 中的 `params.page.mapbox` 部分相同. +- **share**: 和 [网站配置](../theme-documentation-basics#site-configuration) 中的 `params.page.share` 部分相同. +- **comment**: 和 [网站配置](../theme-documentation-basics#site-configuration) 中的 `params.page.comment` 部分相同. +- **library**: 和 [网站配置](../theme-documentation-basics#site-configuration) 中的 `params.page.library` 部分相同. +- **seo**: 和 [网站配置](../theme-documentation-basics#site-configuration) 中的 `params.page.seo` 部分相同. + +{{< admonition tip >}} + +**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 内容摘要 + +**CodeIT** 主题使用内容摘要在主页中显示大致文章信息。Hugo 支持生成文章的摘要. + + + +### 自动摘要拆分 + +默认情况下, Hugo 自动将内容的前 70 个单词作为摘要. + +你可以通过在 [网站配置](../theme-documentation-basics#site-configuration) 中设置 `summaryLength` 来自定义摘要长度. + +如果您要使用 [CJK]^(中文/日语/韩语) 语言创建内容, 并且想使用 Hugo 的自动摘要拆分功能，请在 [网站配置](../theme-documentation-basics#site-configuration) 中将 `hasCJKLanguage` 设置为 `true`. + +### 手动摘要拆分 + +另外, 你也可以添加 `<!--more-->` 摘要分割符来拆分文章生成摘要. + +摘要分隔符之前的内容将用作该文章的摘要. + +{{< admonition >}} +请小心输入`<!--more-->` ; 即全部为小写且没有空格. +{{< /admonition >}} + +### 前置参数摘要 + +你可能希望摘要不是文章开头的文字. 在这种情况下, 你可以在文章前置参数的 `summary` 变量中设置单独的摘要. + +### 使用文章描述作为摘要 + +你可能希望将文章前置参数中的 `description` 变量的内容作为摘要. + +你仍然需要在文章开头添加 `<!--more-->` 摘要分割符. 将摘要分隔符之前的内容保留为空. 然后 **CodeIT** 主题会将你的文章描述作为摘要. + +### 摘要选择的优先级顺序 + +由于可以通过多种方式指定摘要, 因此了解顺序很有用. 如下: + +1. 如果文章中有 `<!--more-->` 摘要分隔符, 但分隔符之前没有内容, 则使用描述作为摘要. +2. 如果文章中有 `<!--more-->` 摘要分隔符, 则将按照手动摘要拆分的方法获得摘要. +3. 如果文章前置参数中有摘要变量, 那么将以该值作为摘要. +4. 按照自动摘要拆分方法. + +{{< admonition >}} +不建议在摘要内容中包含富文本块元素, 这会导致渲染错误. 例如代码块, 图片, 表格等. +{{< /admonition >}} + +## 4 Markdown 基本语法 + +这部分内容在 [Markdown 基本语法页面](../basic-markdown-syntax/) 中介绍. + +## 5 Markdown 扩展语法 {#extended-markdown-syntax} + +**CodeIT** 主题提供了一些扩展的语法便于你撰写文章. + +### Emoji 支持 + +这部分内容在 [Emoji 支持页面](../emoji-support/) 中介绍. + +### 数学公式 + +**CodeIT** 基于 [$ \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} + +**CodeIT** 主题支持一种 **字符注音或者注释** Markdown 扩展语法: + +```markdown +[Hugo]{?^}(一个开源的静态网站生成工具) +``` + +呈现的输出效果如下: + +[Hugo]^(一个开源的静态网站生成工具) + +### 分数 {#fraction} + +**CodeIT** 主题支持一种 **分数** Markdown 扩展语法: + +```markdown +[浅色]{?/}[深色] + +[99]{?/}[100] +``` + +呈现的输出效果如下: + +[浅色]/[深色] + +[90]/[100] + +### Font Awesome {#fontawesome} + +**CodeIT** 主题使用 [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)**. diff --git a/themes/CodeIT/exampleSite/content/posts/theme-documentation-content/summary.png b/themes/CodeIT/exampleSite/content/posts/theme-documentation-content/summary.png Binary files differnew file mode 100644 index 0000000..92c5cb4 --- /dev/null +++ b/themes/CodeIT/exampleSite/content/posts/theme-documentation-content/summary.png diff --git a/themes/CodeIT/exampleSite/content/posts/theme-documentation-content/summary.zh-cn.png b/themes/CodeIT/exampleSite/content/posts/theme-documentation-content/summary.zh-cn.png Binary files differnew file mode 100644 index 0000000..73d271a --- /dev/null +++ b/themes/CodeIT/exampleSite/content/posts/theme-documentation-content/summary.zh-cn.png |
