Genius/hextra
1
0
Fork 0
forked from drowl87/hextra_mirror
Code Pull Requests Activity

docs: add documentations

Browse Source
This commit is contained in:
Xin
2023-08-17 23:09:49 +01:00
parent 824047c3d0
commit ef92d7d627
14 changed files with 224 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
exampleSite/content/docs/guide/_index.md
View File

@ -3,10 +3,20 @@ title: Guide
weight: 2
---
Guide to the project.
Guide to using Hextra to build your site.
{{< cards >}}
{{< card link="/" title="Callout" icon="warning" >}}
{{< card link="/" title="GitHub" icon="github" >}}
{{< card link="/" title="No Icon" >}}
{{< card link="organize-files" title="Organize Files" icon="document-duplicate" >}}
{{< card link="configuration" title="Configuration" icon="adjustments" >}}
{{< card link="markdown" title="Markdown" icon="markdown" >}}
{{< card link="syntax-highlighting" title="Syntax Highlighting" icon="sparkles" >}}
{{< card link="latex" title="LaTeX" icon="variable" >}}
{{< card link="diagrams" title="Diagrams" icon="chart-square-bar" >}}
{{< card link="shortcodes" title="Shortcodes" icon="template" >}}
{{< card link="search" title="Search" icon="document-search" >}}
{{< card link="multi-language" title="Multi-language" icon="translate" >}}
{{< card link="seo" title="SEO" icon="chart-pie" >}}
{{< card link="customization" title="Customization" icon="pencil" >}}
{{< card link="deployment" title="Deployment" icon="server" >}}
{{< card link="faq" title="FAQ" icon="question-mark-circle" >}}
{{< /cards >}}

6
exampleSite/content/docs/guide/components/_index.ja.md Normal file
View File

@ -0,0 +1,6 @@
---
title: コンポーネント
weight: 2
---
Hextraは、[Hugo Shortcodes](https://gohugo.io/content-management/shortcodes/)に基づいたさまざまな組み込みコンポーネントを提供しています。

15
exampleSite/content/docs/guide/components/_index.md Normal file
View File

@ -0,0 +1,15 @@
---
title: Shortcodes
weight: 9
---
Hextra provides a variety of built-in components based on [Hugo Shortcodes](https://gohugo.io/content-management/shortcodes/).
{{< cards >}}
{{< card link="callouts" title="Callouts" icon="warning" >}}
{{< card link="cards" title="Cards" >}}
{{< card link="filetree" title="FileTree" >}}
{{< card link="steps" title="Steps" icon="one" >}}
{{< card link="tabs" title="Tabs" icon="collection" >}}
{{< /cards >}}

74
exampleSite/content/docs/guide/components/callouts.md Normal file
View File

@ -0,0 +1,74 @@
---
title: Callout Component
linkTitle: Callout
---
A built-in component to show important information to the reader.
## Example
{{< callout emoji="👾">}}
A **callout** is a short piece of text intended to attract attention.
{{< /callout >}}
{{< callout type="info" >}}
A **callout** is a short piece of text intended to attract attention.
{{< /callout >}}
{{< callout type="warning" >}}
A **callout** is a short piece of text intended to attract attention.
{{< /callout >}}
{{< callout type="error" >}}
A **callout** is a short piece of text intended to attract attention.
{{< /callout >}}
## Usage
### Default
{{< callout emoji="🌐">}}
Hugo can be used to create a wide variety of websites, including blogs, portfolios, documentation sites, and more.
{{< /callout >}}
```markdown
{{</* callout emoji="🌐" */>}}
Hugo can be used to create a wide variety of websites, including blogs, portfolios, documentation sites, and more.
{{</* /callout */>}}
```
### Info
{{< callout type="info" >}}
Please visit GitHub to see the latest releases.
{{< /callout >}}
```markdown
{{</* callout type="info" */>}}
Please visit GitHub to see the latest releases.
{{</* /callout */>}}
```
### Warning
{{< callout type="warning" >}}
This API will be deprecated in the next version.
{{< /callout >}}
```markdown
{{</* callout type="warning" */>}}
A **callout** is a short piece of text intended to attract attention.
{{</* /callout */>}}
```
### Error
{{< callout type="error" >}}
Something went wrong and it's going to explode.
{{< /callout >}}
```markdown
{{</* callout type="error" */>}}
Something went wrong and it's going to explode.
{{</* /callout */>}}
```

22
exampleSite/content/docs/guide/components/cards.md Normal file
View File

@ -0,0 +1,22 @@
---
title: Cards Component
linkTitle: Cards
---
## Example
{{< cards >}}
{{< card link="/" title="Callout" icon="warning" >}}
{{< card link="/" title="GitHub" icon="github" >}}
{{< card link="/" title="No Icon" >}}
{{< /cards >}}
## Usage
```
{{</* cards */>}}
{{</* card link="/" title="Callout" icon="warning" */>}}
{{</* card link="/" title="GitHub" icon="github" */>}}
{{</* card link="/" title="No Icon" */>}}
{{</* /cards */>}}
```

34
exampleSite/content/docs/guide/components/filetree.md Normal file
View File

@ -0,0 +1,34 @@
---
title: FileTree Component
linkTitle: FileTree
---
## Example
{{< filetree/container >}}
{{< filetree/folder name="content" >}}
{{< filetree/file name="_index.md" >}}
{{< filetree/folder name="docs" state="closed" >}}
{{< filetree/file name="_index.md" >}}
{{< filetree/file name="introduction.md" >}}
{{< filetree/file name="introduction.fr.md" >}}
{{< /filetree/folder >}}
{{< /filetree/folder >}}
{{< filetree/file name="hugo.toml" >}}
{{< /filetree/container >}}
## Usage
```text {filename="Markdown"}
{{</* filetree/container */>}}
{{</* filetree/folder name="content" */>}}
{{</* filetree/file name="_index.md" */>}}
{{</* filetree/folder name="docs" state="closed" */>}}
{{</* filetree/file name="_index.md" */>}}
{{</* filetree/file name="introduction.md" */>}}
{{</* filetree/file name="introduction.fr.md" */>}}
{{</* /filetree/folder */>}}
{{</* /filetree/folder */>}}
{{</* filetree/file name="hugo.toml" */>}}
{{</* /filetree/container */>}}
```

40
exampleSite/content/docs/guide/components/steps.md Normal file
View File

@ -0,0 +1,40 @@
---
title: Steps
---
A built-in component to display a series of steps.
## Example
{{% steps %}}
### Step 1
This is the first step.
### Step 2
This is the second step.
### Step 3
This is the third step.
{{% /steps %}}
## Usage
Put Markdown h3 header within `steps` shortcode.
```
{{%/* steps */%}}
### Step 1
This is the first step.
### Step 2
This is the second step.
{{%/* /steps */%}}
```

51
exampleSite/content/docs/guide/components/tabs.md Normal file
View File

@ -0,0 +1,51 @@
---
title: Tabs
---
## Example
{{< tabs items="JSON,YAML,TOML" >}}
{{< tab >}}**JSON**: JavaScript Object Notation (JSON) is a standard text-based format for representing structured data based on JavaScript object syntax.{{< /tab >}}
{{< tab >}}**YAML**: YAML is a human-readable data serialization language.{{< /tab >}}
{{< tab >}}**TOML**: TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics.{{< /tab >}}
{{< /tabs >}}
## Usage
### Default
```
{{</* tabs items="JSON,YAML,TOML" */>}}
{{</* tab */>}}**JSON**: JavaScript Object Notation (JSON) is a standard text-based format for representing structured data based on JavaScript object syntax.{{</* /tab */>}}
{{</* tab */>}}**YAML**: YAML is a human-readable data serialization language.{{</* /tab */>}}
{{</* tab */>}}**TOML**: TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics.{{</* /tab */>}}
{{</* /tabs */>}}
```
### Specify Selected Index
Use `defaultIndex` property to specify the selected tab. The index starts from 0.
```
{{</* tabs items="JSON,YAML,TOML" defaultIndex="1" */>}}
{{</* tab */>}}**JSON**: JavaScript Object Notation (JSON) is a standard text-based format for representing structured data based on JavaScript object syntax.{{</* /tab */>}}
{{</* tab */>}}**YAML**: YAML is a human-readable data serialization language.{{</* /tab */>}}
{{</* tab */>}}**TOML**: TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics.{{</* /tab */>}}
{{</* /tabs */>}}
```
The `YAML` tab will be selected by default.
{{< tabs items="JSON,YAML,TOML" defaultIndex="1" >}}
{{< tab >}}**JSON**: JavaScript Object Notation (JSON) is a standard text-based format for representing structured data based on JavaScript object syntax.{{< /tab >}}
{{< tab >}}**YAML**: YAML is a human-readable data serialization language.{{< /tab >}}
{{< tab >}}**TOML**: TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics.{{< /tab >}}
{{< /tabs >}}

44
exampleSite/content/docs/guide/latex.md Normal file
View File

@ -0,0 +1,44 @@
---
title: "LaTeX"
weight: 4
math: true
---
$\KaTeX$ is used for rendering LaTeX math expressions. It can be enabled per page by setting `math` to `true` in the page front matter.
```yaml {filename="Markdown"}
---
title: "My Page with LaTeX"
math: true
---
```
When enabled, the scripts, stylesheets and fonts from KaTeX will be included automatically in your site. You can start using LaTeX math expressions in your Markdown content.
## Example
Both inline and separate paragraph LaTeX math expressions are supported in the Markdown content.
### Inline
```markdown {filename="page.md"}
This $\sigma(z) = \frac{1}{1 + e^{-z}}$ is inline.
```
This $\sigma(z) = \frac{1}{1 + e^{-z}}$ is inline.
### Separate Paragraph
```markdown {filename="page.md"}
$$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
```
will be rendered as:
$$F(\omega) = \int_{-\infty}^{\infty} f(t) e^{-j\omega t} \, dt$$
## Supported Functions
For a list of supported functions, see [KaTeX supported functions](https://katex.org/docs/supported.html).

1
exampleSite/content/docs/guide/markdown.md
View File

@ -1,6 +1,7 @@
---
title: Markdown
math: true
weight: 2
---
This article offers a sample of basic Markdown syntax that can be used in Hugo content files, also it shows whether basic HTML elements are decorated with CSS in a Hugo theme.

59
exampleSite/content/docs/guide/organize-files.md
View File

@ -1,5 +1,62 @@
---
title: Organize Files
weight: 1
---
Organize files in the project.
## Directory Structure
By default, Hugo searches for Markdown files in the `content` directory, and the structure of the directory determines the final output structure of your website.
Take the example site as an example:
{{< filetree/container >}}
{{< filetree/folder name="content" >}}
{{< filetree/file name="_index.md" >}}
{{< filetree/folder name="docs" state="open" >}}
{{< filetree/file name="_index.md" >}}
{{< filetree/file name="getting-started.md" >}}
{{< filetree/folder name="guide" state="open" >}}
{{< filetree/file name="_index.md" >}}
{{< filetree/file name="organize-files.md" >}}
{{< /filetree/folder >}}
{{< /filetree/folder >}}
{{< filetree/folder name="blog" state="open" >}}
{{< filetree/file name="_index.md" >}}
{{< filetree/file name="post-1.md" >}}
{{< /filetree/folder >}}
{{< /filetree/folder >}}
{{< /filetree/container >}}
Each of the `_index.md` files is the index page for the corresponding section. The other Markdown files are regular pages.
```
content
├── _index.md // <- /
├── docs
│ ├── _index.md // <- /docs/
│ ├── getting-started.md // <- /docs/getting-started/
│ └── guide
│ ├── _index.md // <- /docs/guide/
│ └── organize-files.md // <- /docs/guide/organize-files/
└── blog
├── _index.md // <- /blog/
└── post-1.md // <- /blog/post-1/
```
## Sidebar Navigation
The sidebar navigation is generated automatically based on the content organization alphabetically. To manually configure the sidebar order, we can use the `weight` parameter in the front matter of the Markdown files.
```yaml {filename="content/docs/guide/_index.md"}
---
title: Guide
weight: 2
---
```
{{< callout emoji="ℹ️">}}
It is recommended to keep the sidebar not too deep. If you have a lot of content, consider **splitting them into multiple sections**.
{{< /callout >}}
## Configure Content Directory
If we need to use a different directory for our content, we can do so by setting the [`contentDir`](https://gohugo.io/getting-started/configuration/#contentdir) parameter in our site configuration file.

87
exampleSite/content/docs/guide/syntax-highlighting.md Normal file
View File

@ -0,0 +1,87 @@
---
title: "Syntax Highlighting"
weight: 3
---
Hugo uses [Chroma](https://github.com/alecthomas/chroma), a general purpose syntax highlighter in pure Go, for syntax highlighting.
It is recommended to use backticks for code blocks in Markdown content. For example:
````markdown {filename="Markdown"}
```python
def say_hello():
print("Hello!")
```
````
will be rendered as:
```python
def say_hello():
print("Hello!")
```
## Features
### Filename
To add a filename or title to the code block, set attribute `filename`:
````markdown {filename="Markdown"}
```python {filename="hello.py"}
def say_hello():
print("Hello!")
```
````
```python {filename="hello.py"}
def say_hello():
print("Hello!")
```
### Line Numbers
To set line numbers, set attribute `linenos` to `table` and optionally set `linenostart` to the starting line number:
````markdown {filename="Markdown"}
```python {linenos=table,linenostart=42}
def say_hello():
print("Hello!")
```
````
```python {linenos=table,linenostart=42}
def say_hello():
print("Hello!")
```
### Highlighting Lines
To highlight lines, set attribute `hl_lines` to a list of line numbers:
````markdown {filename="Markdown"}
```python {linenos=table,hl_lines=[2,4],linenostart=1,filename="hello.py"}
def say_hello():
print("Hello!")
def main():
say_hello()
```
````
```python {linenos=table,hl_lines=[2,4],linenostart=1,filename="hello.py"}
def say_hello():
print("Hello!")
def main():
say_hello()
```
### Copy Button
By default, copy button is enabled for code blocks.
## Supported Languages
For a list of supported languages, please see [Chroma's documentation](https://github.com/alecthomas/chroma#supported-languages).