feat: add more content and fix issues

fix: hide lang switch if site is not multilingual

docs: update getting started page

fix: ordered list style

chore: update hugo icon

feat: add icon shortcode page

docs: add markdown and configuration pages

docs: add diagrams page

docs: add more content

fix: mermaid background and add image styling

chore: update templates

chore: update hugo stats

assets/css/typography.css

@@ -60,7 +60,7 @@
       @apply my-2;
     }
   }
-  .not-prose ul, ol {
+  .not-prose ul, .not-prose ol {
     @apply m-0 list-none;
     li {
       @apply m-0;
@@ -69,6 +69,17 @@
   kbd {
     @apply border-black border-opacity-[0.04] bg-opacity-[0.03] bg-black break-words rounded-md border py-0.5 px-[.25em] text-[.9em] dark:border-white/10 dark:bg-white/10;
   }
+  pre:not(.code-block pre).mermaid {
+    @apply bg-transparent rounded-none dark:bg-transparent;
+  }
+  img {
+    @apply mx-auto my-4 rounded-md;
+  }
+  figure {
+    figcaption {
+      @apply text-sm text-gray-500 dark:text-gray-400 mt-2 block text-center;
+    }
+  }
 }
 
 .subheading-anchor {

data/icons.yaml

@@ -11,14 +11,7 @@ github: >
 
 hextra: <svg viewBox="0 0 180 180" xmlns="http://www.w3.org/2000/svg" fill="currentColor"><path fill-rule="evenodd" clip-rule="evenodd" d="m 105.50024,22.224647 c -9.59169,-5.537563 -21.40871,-5.537563 -31.000093,0 L 39.054693,42.689119 C 29.463353,48.226675 23.55484,58.460531 23.55484,69.535642 v 40.928918 c 0,11.07542 5.908513,21.3092 15.499853,26.84652 l 35.445453,20.46446 c 9.591313,5.53732 21.408404,5.53732 31.000094,0 l 35.44507,-20.46446 c 9.59131,-5.53732 15.49985,-15.7711 15.49985,-26.84652 V 69.535642 c 0,-11.075111 -5.90854,-21.308967 -15.49985,-26.846523 z M 34.112797,85.737639 c -1.384445,2.397827 -1.384445,5.352099 0,7.749927 l 24.781554,42.922974 c 1.38437,2.39783 3.942853,3.87496 6.711592,3.87496 h 49.563107 c 2.76905,0 5.3273,-1.47713 6.71144,-3.87496 l 24.78194,-42.922974 c 1.38414,-2.397828 1.38414,-5.3521 0,-7.749927 L 121.88049,42.814746 c -1.38414,-2.397828 -3.94239,-3.874964 -6.71144,-3.874964 H 65.605944 c -2.768739,0 -5.327223,1.477059 -6.711592,3.874964 z" style="stroke-width:0.774993" /></svg>
 
-hugo: >
+hugo: <svg viewBox="0 0 370 391" xmlns="http://www.w3.org/2000/svg"><g clip-rule="evenodd" fill-rule="evenodd"><path d="m207.5 22.4 114.4 66.6c13.5 7.9 21.9 22.4 21.9 38v136.4c0 17.3-9.3 33.3-24.5 41.8l-113.5 63.9a49.06 49.06 0 0 1 -48.5-.2l-104.5-60.1c-16.4-9.5-26.6-27-26.6-45.9v-129.5c0-19.1 9.9-36.8 26.1-46.8l102.8-63.5c16-9.9 36.2-10.1 52.4-.7z" fill="#ff4088" stroke="#c9177e" stroke-width="27" /><path d="m105.6 298.2v-207.2h43.4v75.5h71.9v-75.5h43.5v207.2h-43.5v-90.6h-71.9v90.6z" fill="#fff" /></g></svg>
-  <svg viewBox="0 0 370 391" xmlns="http://www.w3.org/2000/svg">
-    <g clip-rule="evenodd" fill-rule="evenodd">
-      <path d="m207.5 22.4 114.4 66.6c13.5 7.9 21.9 22.4 21.9 38v136.4c0 17.3-9.3 33.3-24.5 41.8l-113.5 63.9a49.06 49.06 0 0 1 -48.5-.2l-104.5-60.1c-16.4-9.5-26.6-27-26.6-45.9v-129.5c0-19.1 9.9-36.8 26.1-46.8l102.8-63.5c16-9.9 36.2-10.1 52.4-.7z" fill="#ff4088" stroke="#c9177e" stroke-width="27" />
-      <path d="m105.6 298.2v-207.2h43.4v75.5h71.9v-75.5h43.5v207.2h-43.5v-90.6h-71.9v90.6z" fill="#fff" />
-    </g>
-  </svg>
-
 hugo-full: >
   <svg xmlns="http://www.w3.org/2000/svg" fill-rule="evenodd" stroke-width="27" aria-label="Logo" viewBox="0 0 1493 391">
     <path fill="#ebb951" stroke="#fcd804" d="M1345.211 24.704l112.262 64.305a43 43 0 0 1 21.627 37.312v142.237a40 40 0 0 1-20.702 35.037l-120.886 66.584a42 42 0 0 1-41.216-.389l-106.242-61.155a57 57 0 0 1-28.564-49.4V138.71a64 64 0 0 1 31.172-54.939l98.01-58.564a54 54 0 0 1 54.54-.503z"/>

exampleSite/content/docs/advanced/_index.md

@@ -4,6 +4,7 @@ title: Advanced Topics
 ---
 
 {{< cards >}}
-  {{< card link="seo" title="SEO" icon="chart-pie" >}}
+  {{< card link="multi-language" title="Multi-language" icon="translate" >}}
+  {{< card link="deployment" title="Deployment" icon="server" >}}
   {{< card link="customization" title="Customization" icon="pencil" >}}
 {{< /cards >}}

exampleSite/content/docs/getting-started.md

@@ -5,9 +5,13 @@ weight: 1
 
 ## Start as New Project
 
-Before we start, make sure we have [Hugo](https://gohugo.io/) installed. We also need to have Git and Go installed if we want to use Hugo modules.
+### Prerequisites
+
+Before we start, make sure we have [Hugo](https://gohugo.io/) installed.
 Please refer to Hugo's [official installation guide](https://gohugo.io/installation/) for more details.
 
+[Hugo modules](https://gohugo.io/hugo-modules/) are the recommended way to manage Hugo themes. To use Hugo modules, we need to install [Git](https://git-scm.com/) and [Go](https://go.dev/).
+
 {{% steps %}}
 
 ### Initialize a new Hugo site
@@ -16,9 +20,7 @@ Please refer to Hugo's [official installation guide](https://gohugo.io/installat
 $ hugo new site my-site --format=yaml
 ```
 
-### Configure Hextra theme
+### Configure Hextra theme via module
-
-[Hugo modules](https://gohugo.io/hugo-modules/) are the recommended way to manage Hugo themes.
 
 ```shell
 # initialize hugo module
@@ -29,7 +31,7 @@ $ hugo mod init github.com/username/my-site
 $ hugo mod get github.com/imfing/hextra
 ```
 
-Edit `config.yaml` to enable Hextra theme:
+Edit `hugo.yaml` to enable Hextra theme:
 
 ```yaml
 module:
@@ -37,12 +39,32 @@ module:
     - path: github.com/imfing/hextra
 ```
 
-### Run Hugo server
+### Create your first content pages
+
+Let's create a new content page for the home page and the documentation page:
 
 ```shell
-$ hugo server -D
+$ hugo new content/_index.md
+$ hugo new content/docs/_index.md
+```
+
+### Preview the site locally
+
+```shell
+$ hugo server
 ```
 
 Voila! You can see your new site at `http://localhost:1313/`.
 
 {{% /steps %}}
+
+
+## Next
+
+Explore the following sections to start adding more contents:
+
+{{< cards >}}
+  {{< card link="organize-files" title="Organize Files" icon="document-duplicate" >}}
+  {{< card link="configuration" title="Configuration" icon="adjustments" >}}
+  {{< card link="markdown" title="Markdown" icon="markdown" >}}
+{{< /cards >}}

exampleSite/content/docs/guide/_index.md

@@ -13,7 +13,4 @@ Guide to using Hextra to build your site.
   {{< 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="deployment" title="Deployment" icon="server" >}}
 {{< /cards >}}

exampleSite/content/docs/guide/configuration.md

@@ -0,0 +1,126 @@
+---
+title: Configuration
+weight: 2
+---
+
+Hugo reads its configuration from `hugo.yaml` in the root of your Hugo site.
+The config file is where you can configure all aspects of your site.
+You can find the config file for this site in `exampleSite/hugo.yaml` as a good starting point.
+
+## Navigation
+
+### Menu
+
+Top right menu is defined under the `menu.main` section in the config file:
+
+```yaml {filename="hugo.yaml"}
+menu:
+  main:
+    - name: Documentation
+      pageRef: /docs
+      weight: 1
+    - name: Blog
+      pageRef: /blog
+      weight: 2
+    - name: About
+      pageRef: /about
+      weight: 3
+    - name: Search
+      weight: 4
+      params:
+        type: search
+        placeholder: Search Hextra docs...
+    - name: GitHub
+      weight: 5
+      url: "https://github.com/imfing/hextra"
+      params:
+        icon: github
+```
+
+There are different types of menu items:
+
+1. Link to a page in the site with `pageRef`
+    ```yaml
+    - name: Documentation
+      pageRef: /docs
+    ```
+2. Link to an external URL with `url`
+    ```yaml
+    - name: GitHub
+      url: "https://github.com"
+    ```
+3. Search bar with `type: search`
+    ```yaml
+    - name: Search
+      params:
+        type: search
+        placeholder: Search Hextra docs...
+    ```
+4. Icon
+    ```yaml
+    - name: GitHub
+      params:
+        icon: github
+    ```
+
+These menu items can be sorted by setting the `weight` parameter.
+
+## Sidebar
+
+### Main Sidebar
+
+For the main sidebar, it is automatically generated from the structure of the content directory.
+See the [Organize Files](/docs/guide/organize-files) page for more details.
+
+### Extra Links
+
+Sidebar extra links are defined under the `menu.sidebar` section in the config file:
+
+```yaml {filename="hugo.yaml"}
+menu:
+  sidebar:
+    - name: More
+      params:
+        type: separator
+      weight: 1
+    - name: "About"
+      pageRef: "/about"
+      weight: 2
+    - name: "Hugo Docs ↗"
+      url: "https://gohugo.io/documentation/"
+      weight: 3
+```
+
+## Right Sidebar
+
+### Table of Contents
+
+Table of contents is automatically generated from the headings in the content file. It can be disabled by setting `toc: false` in the front matter of the page.
+
+```yaml {filename="content/docs/guide/configuration.md"}
+---
+title: Configuration
+toc: false
+---
+```
+
+### Page Edit Link
+
+To configure the page edit link, we can set the `params.editURL.base` parameter in the config file:
+
+```yaml {filename="hugo.yaml"}
+params:
+  editURL:
+    base: "https://github.com/your-username/your-repo/edit/main"
+```
+
+The edit links will be automatically generated for each page.
+If you want to set edit link for a specific page, you can set the `params.editURL` parameter in the front matter of the page:
+
+```yaml {filename="content/docs/guide/configuration.md"}
+---
+title: Configuration
+params:
+  editURL: "https://example.com/edit/this/page"
+---
+```

exampleSite/content/docs/guide/diagrams.md

@@ -0,0 +1,52 @@
+---
+title: Diagrams
+weight: 6
+---
+
+Currently, Hextra supports [Mermaid](#mermaid) for diagrams.
+
+<!--more-->
+
+## Mermaid
+
+[Mermaid](https://github.com/mermaid-js/mermaid#readme) is a JavaScript based diagramming and charting tool that takes Markdown-inspired text definitions and creates diagrams dynamically in the browser. For example, Mermaid can render flow charts, sequence diagrams, pie charts and more.
+
+Using Mermaid in Hextra is as simple as writing a code block with language set `mermaid`:
+
+````markdown
+```mermaid
+graph TD;
+    A-->B;
+    A-->C;
+    B-->D;
+    C-->D;
+```
+````
+
+will be rendered as:
+
+```mermaid
+graph TD;
+    A-->B;
+    A-->C;
+    B-->D;
+    C-->D;
+```
+
+Sequence diagram:
+
+```mermaid
+sequenceDiagram
+    participant Alice
+    participant Bob
+    Alice->>John: Hello John, how are you?
+    loop Healthcheck
+        John->>John: Fight against hypochondria
+    end
+    Note right of John: Rational thoughts <br/>prevail!
+    John-->>Alice: Great!
+    John->>Bob: How about you?
+    Bob-->>John: Jolly good!
+```
+
+For more information, please refer to [Mermaid Documentation](https://mermaid-js.github.io/mermaid/#/).

exampleSite/content/docs/guide/markdown.md

@@ -1,46 +1,34 @@
 ---
 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.
+Hugo supports [Markdown](https://en.wikipedia.org/wiki/Markdown) syntax for formatting text, creating lists, and more. This page will show you some of the most common Markdown syntax examples.
+
 <!--more-->
 
-## Headings
+## Markdown Examples
 
-The following HTML `<h1>`—`<h6>` elements represent six levels of section headings. `<h1>` is the highest section level while `<h6>` is the lowest.
+### Styling Text
 
-# H1
+| Style   | Syntax     | Example   | Output   |
-## H2
+| --------  | -------- | ------ | ------ |
-### H3
+| Bold | `**bold text**` | `**bold text**` | **bold text** |
-#### H4
+| Italic | `*italicized text*` | `*italicized text* | *italicized text* |
-##### H5
+| Strikethrough | `~~strikethrough text~~` | `~~strikethrough text~~` | ~~strikethrough text~~ |
-###### H6
+| Subscript | `<sub></sub>` | `This is a <sub>subscript</sub> text` | This is a <sub>subscript</sub> text |
+| Superscript | `<sup></sup>` | `This is a <sup>superscript</sup> text` | This is a <sup>superscript</sup> text |
 
-## Paragraph
+### Blockquotes
 
-Xerum, quo qui aut unt expliquam qui dolut labo. Aque venitatiusda cum, voluptionse latur sitiae dolessi aut parist aut dollo enim qui voluptate ma dolestendit peritin re plis aut quas inctum laceat est volestemque commosa as cus endigna tectur, offic to cor sequas etum rerum idem sintibus eiur? Quianimin porecus evelectur, cum que nis nust voloribus ratem aut omnimi, sitatur? Quiatem. Nam, omnis sum am facea corem alique molestrunt et eos evelece arcillit ut aut eos eos nus, sin conecerem erum fuga. Ri oditatquam, ad quibus unda veliamenimin cusam et facea ipsamus es exerum sitate dolores editium rerore eost, temped molorro ratiae volorro te reribus dolorer sperchicium faceata tiustia prat.
+Blockquote with attribution
-
-Itatur? Quiatae cullecum rem ent aut odis in re eossequodi nonsequ idebis ne sapicia is sinveli squiatum, core et que aut hariosam ex eat.
-
-## Blockquotes
-
-The blockquote element represents content that is quoted from another source, optionally with a citation which must be within a `footer` or `cite` element, and optionally with in-line changes such as annotations and abbreviations.
-
-#### Blockquote without attribution
-
-> Tiam, ad mint andaepu dandae nostion secatur sequo quae.
-> **Note** that you can use *Markdown syntax* within a blockquote.
-
-#### Blockquote with attribution
 
 > Don't communicate by sharing memory, share memory by communicating.<br>
 > — <cite>Rob Pike[^1]</cite>
 
 [^1]: The above quote is excerpted from Rob Pike's [talk](https://www.youtube.com/watch?v=PAAkCSZUG1c) during Gopherfest, November 18, 2015.
 
-## Tables
+### Tables
 
 Tables aren't part of the core Markdown spec, but Hugo supports them out-of-the-box.
 
@@ -55,65 +43,13 @@ Tables aren't part of the core Markdown spec, but Hugo supports them out-of-the-
 | --------  | -------- | ------ |
 | *italics* | **bold** | `code` |
 
-## Code Blocks
+### Code Blocks
 
-### Code block with triple backticks
+{{< cards >}}
+    {{< card link="syntax-highlighting" title="Syntax Highlighting" icon="sparkles" >}}
+{{< /cards >}}
 
-```
+### Lists
-def say_hello():
-    print("Hello!")
-```
-
-
-```python
-def say_hello():
-    print("Hello!")
-```
-
-### Code block with filename
-
-```python {filename="hello.py"}
-def say_hello():
-    print("Hello!")
-```
-
-### Code block highlight with line numbers
-
-```python {linenos=table,hl_lines=[1, 2],linenostart=1}
-def say_hello():
-    print("Hello!")
-
-def main():
-    say_hello()
-```
-
-```python {linenos=table,hl_lines=[1, 2],linenostart=1,filename="hello.py"}
-def say_hello():
-    print("Hello!")
-
-def main():
-    say_hello()
-```
-
-## Diagrams
-
-[Mermaid](https://github.com/mermaid-js/mermaid#readme) is a JavaScript based diagramming and charting tool that takes Markdown-inspired text definitions and creates diagrams dynamically in the browser.
-
-```mermaid
-sequenceDiagram
-    participant Alice
-    participant Bob
-    Alice->>John: Hello John, how are you?
-    loop Healthcheck
-        John->>John: Fight against hypochondria
-    end
-    Note right of John: Rational thoughts <br/>prevail!
-    John-->>Alice: Great!
-    John->>Bob: How about you?
-    Bob-->>John: Jolly good!
-```
-
-## List Types
 
 #### Ordered List
 
@@ -137,35 +73,34 @@ sequenceDiagram
   * Milk
   * Cheese
 
-## Math
+### Images
 
-[KaTeX](https://github.com/KaTeX/KaTeX) is a fast math typesetting library for the web. It uses javascript for client-side rendering.
+![](https://source.unsplash.com/featured/800x600?landscape)
 
-### Inline
+With caption:
 
-```
+![](https://source.unsplash.com/featured/800x600?landscape "Unsplash Landscape")
-This $\int\limits_1^\infty \frac{1}{k}\,dk$ is inline.
+
+## Configuration
+
+Hugo uses [Goldmark](https://github.com/yuin/goldmark) for Markdown parsing.
+Markdown rendering can be configured in `hugo.yaml` under `markup.goldmark`.
+Below is the default configuration for Hextra:
+
+```yaml {filename="hugo.yaml"}
+markup:
+  goldmark:
+    renderer:
+      unsafe: true
+  highlight:
+    noClasses: false
 ```
 
-This $\int\limits_1^\infty \frac{1}{k}\,dk$ is inline.
+For more configuration options, see Hugo documentation on [Configure Markup](https://gohugo.io/getting-started/configuration-markup/).
 
-### Separate Paragraph
+## Learning Resources
 
-```
+* [Markdown Guide](https://www.markdownguide.org/)
-$$f(x) = \int_{-\infty}^\infty \hat f(\xi)\,e^{2 \pi i \xi x} \,d\xi$$
+* [Markdown Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)
-```
+* [Markdown Tutorial](https://www.markdowntutorial.com/)
-
+* [Markdown Reference](https://commonmark.org/help/)
-$$f(x) = \int_{-\infty}^\infty \hat f(\xi)\,e^{2 \pi i \xi x} \,d\xi$$
-
-
-## Other Elements — abbr, sub, sup, kbd, mark
-
-<abbr title="Graphics Interchange Format">GIF</abbr> is a bitmap image format.
-
-H<sub>2</sub>O
-
-X<sup>n</sup> + Y<sup>n</sup> = Z<sup>n</sup>
-
-Press <kbd>CTRL</kbd>+<kbd>ALT</kbd>+<kbd>Delete</kbd> to end the session.
-
-Most <mark>salamanders</mark> are nocturnal, and hunt for insects, worms, and other small creatures.

exampleSite/content/docs/guide/shortcodes/icon.md

@@ -0,0 +1,38 @@
+---
+title: Icon
+---
+
+To use this shortcode inline, make sure you have enabled the inline shortcode in the config:
+
+```yaml {filename="hugo.yaml"}
+enableInlineShortcodes: true
+```
+
+The list of available icons can be found in `data/icon.yaml`.
+
+## Example
+
+{{< icon "academic-cap" >}}
+{{< icon "cake" >}}
+{{< icon "gift" >}}
+{{< icon "sparkles" >}}
+
+## Usage
+
+```
+{{</* icon "github" */>}}
+```
+
+[Heroicons](https://v1.heroicons.com/) v1 outline icons are available out of the box.
+
+You can also add your own icons by adding them to `data/icon.yaml`:
+
+```yaml {filename="data/icon.yaml"}
+your-icon: <svg>your icon svg content</svg>
+```
+
+which can then be used like this:
+
+```
+{{</* icon "your-icon" */>}}
+```

exampleSite/hugo_stats.json

@@ -11,8 +11,11 @@
       "button",
       "cite",
       "code",
+      "del",
       "div",
       "em",
+      "figcaption",
+      "figure",
       "footer",
       "g",
       "h1",
@@ -24,6 +27,7 @@
       "head",
       "hr",
       "html",
+      "img",
       "input",
       "kbd",
       "li",

layouts/_default/_markup/render-heading.html

@@ -5,3 +5,4 @@
     <a href="#{{ .Anchor | safeURL }}" class="subheading-anchor" aria-label="Permalink for this section"></a>
   {{- end -}}
 </h{{ .Level }}>
+{{- /* Drop trailing newlines */ -}}

layouts/_default/_markup/render-image.html

@@ -0,0 +1,8 @@
+{{- if .Title -}}
+  <figure>
+    <img src="{{ .Destination | safeURL }}" title="{{ .Title }}" alt="{{ .PlainText | safeHTML }}" loading="lazy" />
+    <figcaption>{{ .Title }}</figcaption>
+  </figure>
+{{- else -}}
+  <img src="{{ .Destination | safeURL }}" alt="{{ .PlainText | safeHTML }}" loading="lazy" />
+{{- end -}}

layouts/partials/sidebar.html

@@ -44,9 +44,15 @@
   </div>
   {{/* Hide theme switch when sidebar is disabled */}}
   {{ $switchesClass := cond $disableSidebar "md:hidden" "" }}
-  <div class="{{ $switchesClass }} sticky bottom-0 bg-white dark:bg-dark mx-4 py-4 shadow-[0_-12px_16px_#fff] flex justify-end items-center gap-2 dark:border-neutral-800 dark:shadow-[0_-12px_16px_#111] contrast-more:border-neutral-400 contrast-more:shadow-none contrast-more:dark:shadow-none border-t" data-toggle-animation="show">
+  <div class="{{ $switchesClass }} {{ with site.IsMultiLingual }}justify-end{{ end }} sticky bottom-0 bg-white dark:bg-dark mx-4 py-4 shadow-[0_-12px_16px_#fff] flex items-center gap-2 dark:border-neutral-800 dark:shadow-[0_-12px_16px_#111] contrast-more:border-neutral-400 contrast-more:shadow-none contrast-more:dark:shadow-none border-t" data-toggle-animation="show">
-    {{ partial "language-switch" (dict "context" $context "grow" true) }}
+    {{- with site.IsMultiLingual }}
-    {{ partial "theme-toggle" (dict "hideLabel" true) }}
+      {{ partial "language-switch" (dict "context" $context "grow" true) }}
+      {{ partial "theme-toggle" (dict "hideLabel" true) }}
+    {{ else }}
+      <div class="flex grow flex-col">
+        {{ partial "theme-toggle" }}
+      </div>
+    {{ end -}}
   </div>
 </aside>
 

layouts/shortcodes/cards.html

@@ -1,3 +1,5 @@
-<div class="hextra-cards mt-4 gap-4 grid not-prose" style="--rows: 3;">
+{{ $rows := .Get "rows" | default "3" }}
+
+<div class="hextra-cards mt-4 gap-4 grid not-prose" style="--rows: {{ $rows }};">
   {{ .Inner }}
 </div>