diff --git a/exampleSite/content/docs/_index.md b/exampleSite/content/docs/_index.md index c794768..4d43aa5 100644 --- a/exampleSite/content/docs/_index.md +++ b/exampleSite/content/docs/_index.md @@ -5,19 +5,24 @@ title: Introduction Welcome to the Hextra documentation! - ## What is Hextra? -**Hextra** is a modern, responsive and powerful [Hugo](https://gohugo.io/) theme built with [Tailwind CSS](https://tailwindcss.com/), inspired by Next.js theme [Nextra](https://github.com/shuding/nextra). +**Hextra** is a modern, responsive and powerful [Hugo](https://gohugo.io/) theme built with [Tailwind CSS](https://tailwindcss.com/). It is inspired by Next.js theme [Nextra](https://github.com/shuding/nextra). + It is designed for building websites for documentation, blogs, books and landing pages. -It is elegant and easy to use out of the box, but also highly customizable to fit your needs. +It is easy to use out of the box, and batteries are included to make your site fast and beautiful. -### Features +## Features -- **Fast** - Built with Hugo and Tailwind CSS, Hextra is extremely fast. +- **Fast** - Hextra is built with Hugo, one of the fastest static site generators. Build and preview your site in just milliseconds. +- **Lightweight** - No need to use Node.js, npm, or any other heavy tooling to build your site. Hextra is solely dependent on Hugo, a single binary file. +- **Responsive** - Hextra looks great on mobile, tablet, and desktop. It also supports dark mode. +- **Full-text Search** - Hextra comes with built-in full-text search powered by [FlexSearch](https://github.com/nextapps-de/flexsearch). +- **Battery included** - Hextra supports Markdown, syntax highlighting, LaTeX, diagrams, and comes with Shortcodes components as building blocks for your Markdown content. +- **Muliti-language** - Hextra supports multi-language sites out of the box. +- **SEO friendly** - Hextra is optimized for search engines with support for Open Graph. +- **Customizable** - Hextra can be extended with your own templates and styles. -## Why Hextra? - -Hextra is based on [Hugo](https://gohugo.io/), a static site generator written in Go, which means you can build your website once and host it anywhere. - -Unlike Next.js, Hugo is **extremely fast**, which enables us to focus on iterating the content and previewing the changes in real time. +{{< cards >}} +{{< card link="/" title="Getting Started" icon="play" >}} +{{< /cards >}} diff --git a/exampleSite/content/docs/guide/_index.md b/exampleSite/content/docs/guide/_index.md index 06063f3..a3f0c42 100644 --- a/exampleSite/content/docs/guide/_index.md +++ b/exampleSite/content/docs/guide/_index.md @@ -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 >}} diff --git a/exampleSite/content/docs/components/_index.ja.md b/exampleSite/content/docs/guide/components/_index.ja.md similarity index 51% rename from exampleSite/content/docs/components/_index.ja.md rename to exampleSite/content/docs/guide/components/_index.ja.md index 0c70a09..6edfed5 100644 --- a/exampleSite/content/docs/components/_index.ja.md +++ b/exampleSite/content/docs/guide/components/_index.ja.md @@ -4,10 +4,3 @@ weight: 2 --- Hextraは、[Hugo Shortcodes](https://gohugo.io/content-management/shortcodes/)に基づいたさまざまな組み込みコンポーネントを提供しています。 - - -{{< cards >}} - {{< card link="callouts" title="Callouts" icon="warning" >}} - {{< card link="cards" title="Cards" icon="cards" >}} - {{< card link="steps" title="Steps" icon="one" >}} -{{< /cards >}} diff --git a/exampleSite/content/docs/components/_index.md b/exampleSite/content/docs/guide/components/_index.md similarity index 61% rename from exampleSite/content/docs/components/_index.md rename to exampleSite/content/docs/guide/components/_index.md index 147291e..8861e67 100644 --- a/exampleSite/content/docs/components/_index.md +++ b/exampleSite/content/docs/guide/components/_index.md @@ -1,5 +1,6 @@ --- -title: Components +title: Shortcodes +weight: 9 --- Hextra provides a variety of built-in components based on [Hugo Shortcodes](https://gohugo.io/content-management/shortcodes/). @@ -7,6 +8,8 @@ Hextra provides a variety of built-in components based on [Hugo Shortcodes](http {{< cards >}} {{< card link="callouts" title="Callouts" icon="warning" >}} - {{< card link="cards" title="Cards" icon="cards" >}} + {{< 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 >}} diff --git a/exampleSite/content/docs/components/callouts.md b/exampleSite/content/docs/guide/components/callouts.md similarity index 100% rename from exampleSite/content/docs/components/callouts.md rename to exampleSite/content/docs/guide/components/callouts.md diff --git a/exampleSite/content/docs/components/cards.md b/exampleSite/content/docs/guide/components/cards.md similarity index 100% rename from exampleSite/content/docs/components/cards.md rename to exampleSite/content/docs/guide/components/cards.md diff --git a/exampleSite/content/docs/components/filetree.md b/exampleSite/content/docs/guide/components/filetree.md similarity index 100% rename from exampleSite/content/docs/components/filetree.md rename to exampleSite/content/docs/guide/components/filetree.md diff --git a/exampleSite/content/docs/components/steps.md b/exampleSite/content/docs/guide/components/steps.md similarity index 100% rename from exampleSite/content/docs/components/steps.md rename to exampleSite/content/docs/guide/components/steps.md diff --git a/exampleSite/content/docs/components/tabs.md b/exampleSite/content/docs/guide/components/tabs.md similarity index 100% rename from exampleSite/content/docs/components/tabs.md rename to exampleSite/content/docs/guide/components/tabs.md diff --git a/exampleSite/content/docs/guide/latex.md b/exampleSite/content/docs/guide/latex.md new file mode 100644 index 0000000..220a7f0 --- /dev/null +++ b/exampleSite/content/docs/guide/latex.md @@ -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). diff --git a/exampleSite/content/docs/guide/markdown.md b/exampleSite/content/docs/guide/markdown.md index c326270..dd0eece 100644 --- a/exampleSite/content/docs/guide/markdown.md +++ b/exampleSite/content/docs/guide/markdown.md @@ -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. diff --git a/exampleSite/content/docs/guide/organize-files.md b/exampleSite/content/docs/guide/organize-files.md index 8631727..2f4549a 100644 --- a/exampleSite/content/docs/guide/organize-files.md +++ b/exampleSite/content/docs/guide/organize-files.md @@ -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. diff --git a/exampleSite/content/docs/guide/syntax-highlighting.md b/exampleSite/content/docs/guide/syntax-highlighting.md new file mode 100644 index 0000000..0010823 --- /dev/null +++ b/exampleSite/content/docs/guide/syntax-highlighting.md @@ -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). diff --git a/exampleSite/content/showcase/index.md b/exampleSite/content/showcase/index.md deleted file mode 100644 index fe0e0d9..0000000 --- a/exampleSite/content/showcase/index.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: Showcase ----