Theme Documentation - Content

Find out how to create and organize your content quickly and intuitively in DoIt theme.

1 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

2 Author Settings

You are encouraged to create your author profile under mysite/data/authors as author_name.toml. In your profile, you can specify the link, email and name with i18n support.

Here is an example for Alice.toml:

link = "https://alice.example.com"
email = "alice@example.com"
name = "Alice"
[zh-cn]
    name = "爱丽丝"

After creating your author profile, you can specify your name in the front matter of your posts. After that, the post will be automatically signed with your name and link, and will be classified according to its author.

---
authors: [Alice]
---

You can also specify multiple authors for one post.

---
authors: [Alice, Bob, Catherine]
---

3 Front Matter

Hugo allows you to add front matter in yaml, toml or json to your content files.

Here is a front matter example:

---
title: "My First Post"
subtitle: ""
date: 2020-03-04T15:58:26+08:00
lastmod: 2020-03-04T15:58:26+08:00
draft: true
authors: []
description: ""
license: ""
images: []

tags: []
categories: []
series: []
series_weight: 1
seriesNavigation: true
featuredImage: ""
featuredImagePreview: ""

hiddenFromHomePage: false
hiddenFromSearch: false
twemoji: false
lightgallery: true
ruby: true
fraction: true
linkToMarkdown: true
linkToSource: false
linkToEdit: false
linkToReport: false
rssFullText: false
license: ''

toc:
  enable: true
  auto: true
code:
  copy: true
  # ...
table:
  sort: 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: []
  # ...
outdatedArticleReminder:
  enable: false
  # ...
sponsor:
  enable: false
  # ...
related:
  enable: false
---

• 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.

• 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.

• authors: the list of authors for the content.

• description: the description for the content.

• license: the special license for this content.

• images: page images for Open Graph and Twitter Cards.

• tags: the tags for the content.

• categories: the categories for the content.

• series: the series for the content.

• series_weight: define the position of the post in the series.

• seriesNavigation: whether to enable series navigation.

• 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.

• fraction: if true, the content will enable the fraction extended syntax.

• linkToMarkdown: if true, the footer of the content will be shown the link to the original Markdown file.

• linkToSource: if false, turn off the view source link in the footer. You can set it to the link to the source file of the post. Use the magic variable {path} to specify the relative path of the post, for example, the {path} for this post is posts/theme-documentation-content/index.en.md.

• linkToEdit: if false, turn off the edit this page link in the footer. You can set it to the link to edit the page. Use the magic variable {path} to specify the relative path of the post, for example, the {path} for this post is posts/theme-documentation-content/index.en.md.

• linkToReport: if false, turn off the report issue link in the footer. You can set it to the link to report issues about the page. Use the magic variables: {path} to specify the relative path of the post, for example, the {path} for this post is posts/theme-documentation-content/index.en.md, {title} to specify the title of the post, for example, the {title} for this post is Theme Documentation - Content and {url} to specify the url of the post, for example, the {url} for this post is https://hugodoit.pages.dev/theme-documentation-content/.

• rssFullText: if true, the full text content will be shown in RSS.

• enableLastMod: if true, the last modified time will be shown in the header.

• enableWordCount: if true, the word count will be shown in the header.

• enableReadingTime: if true, the reading time will be shown in the header.

• license: set the license info (HTML format is supported).

• toc: the same as the params.page.toc part in the site configuration.

• code: the same as the params.page.code part in the site configuration.

• table: the same as the params.page.table part in the site configuration.

• math: the same as the params.page.math part in the site configuration.

• mapbox: the same as the params.page.mapbox part in the site configuration.

• share: the same as the params.page.share part in the site configuration.

• comment: the same as the params.page.comment part in the site configuration.

• library: the same as the params.page.library part in the site configuration.

• seo: the same as the params.page.seo part in the site configuration.

• outdatedArticleReminder: the same as the params.page.outdatedArticleReminder part in the site configuration.

• sponsor: the same as the params.sponsor part in the site configuration.

• related: the same as the params.page.related part in the site configuration.

resources:
- name: featured-image
  src: featured-image.jpg
- name: featured-image-preview
  src: featured-image-preview.jpg

4 Content Summaries

DoIt theme uses the summary of the content to display abstract information in the home page. Hugo can generate summaries of your content.

4.1 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.

If you are creating content in a CJKChinese/Japanese/Korean language and want to use Hugo’s automatic summary splitting, set hasCJKLanguage to true in your site configuration.

4.2 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.

4.3 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.

4.4 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 DoIt theme will use your description as the summary.

4.5 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.

5 Basic Markdown Syntax

This part is shown in the basic markdown syntax page.

6 Extended Markdown Syntax

DoIt theme has some extended syntax elements for you to write articles.

6.1 Emoji Support

This part is shown in the emoji support page.

6.2 Mathematical Formula

DoIt theme supports mathematical formulas based on $ \KaTeX $.

Set the followings in your site configuration to enable mathematical formulas.

[markup]
  [markup.goldmark]
    [markup.goldmark.extensions]
      [markup.goldmark.extensions.passthrough]
        enable = true
        [markup.goldmark.extensions.passthrough.delimiters]
          block = [['\[', '\]']]
          inline = [['\(', '\)']]
[params]
  [page]
    [page.math]
      enable = true
      blockLeftDelimiter = '\['
      blockRightDelimiter = '\]'
      inlineLeftDelimiter = '\('
      inlineRightDelimiter = '\)'
      copyTex = true
      mhchem = true

6.2.1 Block Formula

The default block delimiters is \[ \]:

\[ 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 ]

6.2.2 Inline Formula

The default inline delimiters is \( \):

\( 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 )

6.2.3 Copy-tex

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 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.

6.2.4 mhchem

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 to enable mhchem.

\[ \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-} ]

6.3 Ruby Annotation

An extended Markdown syntax for ruby annotation is supported in DoIt theme:

[Hugo]^(An open-source static site generator)

The rendered output looks like this:

HugoAn open-source static site generator

6.4 Fraction

An extended Markdown syntax for fraction is supported in DoIt theme:

[Light]/[Dark]

[99]/[100]

The rendered output looks like this:

^Light/_Dark

⁹⁰/₁₀₀

6.5 Blockquote

DoIt supports GitHub-style blockquotes:

> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

The rendered output looks like this:

[!NOTE] Useful information that users should know, even when skimming content.

[!TIP] Helpful advice for doing things better or more easily.

[!IMPORTANT] Key information users need to know to achieve their goal.

[!WARNING] Urgent info that needs immediate user attention to avoid problems.

[!CAUTION] Advises about risks or negative outcomes of certain actions.