diff --git a/assets/css/typography.css b/assets/css/typography.css index bb4aa4c..fc44c14 100644 --- a/assets/css/typography.css +++ b/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 { diff --git a/data/icons.yaml b/data/icons.yaml index 21c70cd..1eecbe4 100644 --- a/data/icons.yaml +++ b/data/icons.yaml @@ -11,14 +11,7 @@ github: > hextra: -hugo: > - - - - - - - +hugo: hugo-full: > diff --git a/exampleSite/content/docs/advanced/_index.md b/exampleSite/content/docs/advanced/_index.md index ec7d542..b846769 100644 --- a/exampleSite/content/docs/advanced/_index.md +++ b/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 >}} diff --git a/exampleSite/content/docs/getting-started.md b/exampleSite/content/docs/getting-started.md index 59b8f0d..e3e3526 100644 --- a/exampleSite/content/docs/getting-started.md +++ b/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 - -[Hugo modules](https://gohugo.io/hugo-modules/) are the recommended way to manage Hugo themes. +### Configure Hextra theme via module ```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 >}} diff --git a/exampleSite/content/docs/guide/_index.md b/exampleSite/content/docs/guide/_index.md index 954f3dd..41a7af5 100644 --- a/exampleSite/content/docs/guide/_index.md +++ b/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 >}} diff --git a/exampleSite/content/docs/guide/configuration.md b/exampleSite/content/docs/guide/configuration.md new file mode 100644 index 0000000..326208e --- /dev/null +++ b/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" +--- +``` diff --git a/exampleSite/content/docs/guide/diagrams.md b/exampleSite/content/docs/guide/diagrams.md new file mode 100644 index 0000000..8c2ab2b --- /dev/null +++ b/exampleSite/content/docs/guide/diagrams.md @@ -0,0 +1,52 @@ +--- +title: Diagrams +weight: 6 +--- + +Currently, Hextra supports [Mermaid](#mermaid) for diagrams. + + + +## 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
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/#/). diff --git a/exampleSite/content/docs/guide/markdown.md b/exampleSite/content/docs/guide/markdown.md index dd0eece..2ad9d26 100644 --- a/exampleSite/content/docs/guide/markdown.md +++ b/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. + -## Headings +## Markdown Examples -The following HTML `

`—`

` elements represent six levels of section headings. `

` is the highest section level while `

` is the lowest. +### Styling Text -# H1 -## H2 -### H3 -#### H4 -##### H5 -###### H6 +| Style | Syntax | Example | Output | +| -------- | -------- | ------ | ------ | +| Bold | `**bold text**` | `**bold text**` | **bold text** | +| Italic | `*italicized text*` | `*italicized text* | *italicized text* | +| Strikethrough | `~~strikethrough text~~` | `~~strikethrough text~~` | ~~strikethrough text~~ | +| Subscript | `` | `This is a subscript text` | This is a subscript text | +| Superscript | `` | `This is a superscript text` | This is a superscript 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. - -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 +Blockquote with attribution > Don't communicate by sharing memory, share memory by communicating.
> — Rob Pike[^1] [^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 >}} -``` -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
prevail! - John-->>Alice: Great! - John->>Bob: How about you? - Bob-->>John: Jolly good! -``` - -## List Types +### Lists #### 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: -``` -This $\int\limits_1^\infty \frac{1}{k}\,dk$ is inline. +![](https://source.unsplash.com/featured/800x600?landscape "Unsplash Landscape") + +## 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 -``` -$$f(x) = \int_{-\infty}^\infty \hat f(\xi)\,e^{2 \pi i \xi x} \,d\xi$$ -``` - -$$f(x) = \int_{-\infty}^\infty \hat f(\xi)\,e^{2 \pi i \xi x} \,d\xi$$ - - -## Other Elements — abbr, sub, sup, kbd, mark - -GIF is a bitmap image format. - -H2O - -Xn + Yn = Zn - -Press CTRL+ALT+Delete to end the session. - -Most salamanders are nocturnal, and hunt for insects, worms, and other small creatures. +* [Markdown Guide](https://www.markdownguide.org/) +* [Markdown Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) +* [Markdown Tutorial](https://www.markdowntutorial.com/) +* [Markdown Reference](https://commonmark.org/help/) diff --git a/exampleSite/content/docs/guide/shortcodes/icon.md b/exampleSite/content/docs/guide/shortcodes/icon.md new file mode 100644 index 0000000..2d1e27b --- /dev/null +++ b/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 + +``` +{{}} +``` + +[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: your icon svg content +``` + +which can then be used like this: + +``` +{{}} +``` diff --git a/exampleSite/hugo_stats.json b/exampleSite/hugo_stats.json index f59b6f2..6a33fce 100644 --- a/exampleSite/hugo_stats.json +++ b/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", diff --git a/layouts/_default/_markup/render-heading.html b/layouts/_default/_markup/render-heading.html index 23489d0..a6f836a 100644 --- a/layouts/_default/_markup/render-heading.html +++ b/layouts/_default/_markup/render-heading.html @@ -5,3 +5,4 @@ {{- end -}} +{{- /* Drop trailing newlines */ -}} diff --git a/layouts/_default/_markup/render-image.html b/layouts/_default/_markup/render-image.html new file mode 100644 index 0000000..953d87b --- /dev/null +++ b/layouts/_default/_markup/render-image.html @@ -0,0 +1,8 @@ +{{- if .Title -}} +
+ {{ .PlainText | safeHTML }} +
{{ .Title }}
+
+{{- else -}} + {{ .PlainText | safeHTML }} +{{- end -}} diff --git a/layouts/partials/sidebar.html b/layouts/partials/sidebar.html index 40e3937..80a8e94 100644 --- a/layouts/partials/sidebar.html +++ b/layouts/partials/sidebar.html @@ -44,9 +44,15 @@ {{/* Hide theme switch when sidebar is disabled */}} {{ $switchesClass := cond $disableSidebar "md:hidden" "" }} -
- {{ partial "language-switch" (dict "context" $context "grow" true) }} - {{ partial "theme-toggle" (dict "hideLabel" true) }} +
+ {{- with site.IsMultiLingual }} + {{ partial "language-switch" (dict "context" $context "grow" true) }} + {{ partial "theme-toggle" (dict "hideLabel" true) }} + {{ else }} +
+ {{ partial "theme-toggle" }} +
+ {{ end -}}
diff --git a/layouts/shortcodes/cards.html b/layouts/shortcodes/cards.html index ad44f7d..3b9e5fd 100644 --- a/layouts/shortcodes/cards.html +++ b/layouts/shortcodes/cards.html @@ -1,3 +1,5 @@ -
+{{ $rows := .Get "rows" | default "3" }} + +
{{ .Inner }}