diff options
| author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2022-03-08 19:39:33 +0100 |
|---|---|---|
| committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2022-03-08 19:39:33 +0100 |
| commit | 9d76b8fa34436d87ff023d95c39d60144ccd7f4d (patch) | |
| tree | d157e6a0b8427ad4e3eb32e61a60c799f7d4f6d1 /docs | |
| parent | 4576c82ed462bc9c3934f76181101df1c5a4157e (diff) | |
| parent | d706529720b3b2ccb99719ccd578062ca25a0cc2 (diff) | |
Merge commit 'd706529720b3b2ccb99719ccd578062ca25a0cc2'
Diffstat (limited to 'docs')
23 files changed, 389 insertions, 270 deletions
diff --git a/docs/.cspell.json b/docs/.cspell.json new file mode 100644 index 000000000..70811e515 --- /dev/null +++ b/docs/.cspell.json @@ -0,0 +1,155 @@ +{ + "version": "0.2", + "words": [ + "aabb", + "aabba", + "aabbaa", + "aabbaabb", + "abourget", + "adoc", + "algolia", + "anchorize", + "anthonyfok", + "asciidoctor", + "attrlink", + "Bjørn", + "blackfriday", + "blogue", + "bogem", + "Brotli", + "canonify", + "Catwoman", + "Cheatsheet", + "chromastyles", + "clockoon", + "Cloudinary", + "CNAME", + "Codecademy's", + "CODEOWNERS", + "Commento", + "Cond", + "Contentful", + "countrunes", + "countwords", + "crossreferences", + "digitalcraftsman", + "Disqus", + "dokuwiki", + "DRING", + "Emojify", + "Enwrite", + "eparis", + "errorf", + "firstpost", + "Francia", + "freenode", + "funcs", + "funcsig", + "Garen", + "Getenv", + "Gohugo", + "gohugoio", + "goldenbridge", + "Goldmark", + "gomodules", + "GOPATH", + "govendor", + "Gowans", + "Grayscale", + "Gruber", + "gtag", + "Hokus", + "hugodoc", + "hugolang", + "hugoversion", + "Hyvor", + "iframes", + "imgproc", + "indice", + "Intelli", + "interdoc", + "IPTC", + "Isset", + "Isso", + "Joomla", + "jsonify", + "katex", + "kubernetes", + "lastmod", + "linktitle", + "markdownified", + "markdownify", + "mathjax", + "mercredi", + "Mittwoch", + "mmark", + "monokai", + "Morling", + "Muut", + "mypartials", + "mypost", + "needsexample", + "nobr", + "nocopy", + "Norsk", + "novembre", + "Octopress", + "opengraph", + "OWASP", + "Pandoc", + "peaceiris", + "Pedersen", + "plainify", + "println", + "publishdate", + "Pygments", + "querify", + "readfile", + "REDIR", + "reftext", + "relatedfuncs", + "relref", + "remarkjs", + "rgba", + "rlimit", + "safejs", + "Samsa", + "Shortcode", + "Shortcodes", + "Sindre", + "Smartcrop", + "struct", + "Talkyard", + "taxo", + "tbody", + "tdewolff", + "testshortcodes", + "thead", + "Thinkful", + "TMPDIR", + "tojson", + "Torikian", + "totoml", + "toyaml", + "Unmarshal", + "urlize", + "vimrc", + "wanghc", + "Wappalyzer", + "warnf", + "webp", + "wibble", + "workson", + "zzbbaabb" + ], + "language": "en,en-GB,en-US,de,fr", + "files": [ + "**/*.md" + ], + "ignorePaths": [ + ".cspell.json", + "**/node_modules/**", + "*.min.*" + ], + "useGitignore": true +} diff --git a/docs/.github/workflows/spellcheck.yml b/docs/.github/workflows/spellcheck.yml new file mode 100644 index 000000000..0129bbb27 --- /dev/null +++ b/docs/.github/workflows/spellcheck.yml @@ -0,0 +1,17 @@ +name: 'Check spelling' +on: # rebuild any PRs and main branch changes + push: + branches-ignore: + - "dependabot/**" + pull_request: + +jobs: + spellcheck: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: streetsidesoftware/cspell-action@3bc52c39528d0214a947ff7f8b5c23ad3273435b + with: + inline: warning + strict: false + incremental_files_only: true diff --git a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/baseof.html b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/baseof.html index e2886a0b8..527547428 100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/baseof.html +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/baseof.html @@ -58,6 +58,7 @@ </head> <body class="ma0 sans-serif bg-primary-color-light{{ with getenv "HUGO_ENV" }} {{ . }}{{ end }}"> + {{ partial "hooks/after-body-start" . }} {{ block "nav" . }}{{ partial "site-nav.html" . }}{{ end }} {{ block "header" . }}{{ end }} <main role="main" class="content-with-sidebar min-vh-100 pb7 pb0-ns"> @@ -65,6 +66,9 @@ </main> {{ block "footer" . }}{{ partialCached "site-footer.html" . }}{{ end }} + + {{ partial "hooks/before-body-end" . }} + {{ if .Page.Store.Get "hasMermaid" }} <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script> diff --git a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/hooks/after-body-start.html b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/hooks/after-body-start.html new file mode 100644 index 000000000..426abd018 --- /dev/null +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/hooks/after-body-start.html @@ -0,0 +1 @@ +{{/* Deliberately empty */}} diff --git a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/hooks/before-body-end.html b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/hooks/before-body-end.html new file mode 100644 index 000000000..426abd018 --- /dev/null +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/hooks/before-body-end.html @@ -0,0 +1 @@ +{{/* Deliberately empty */}} diff --git a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/site-nav.html b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/site-nav.html index 0266c9939..749c699e6 100644 --- a/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/site-nav.html +++ b/docs/_vendor/github.com/gohugoio/gohugoioTheme/layouts/partials/site-nav.html @@ -8,7 +8,7 @@ HUGO </a> </h1> - <ul class="list ma0 pa0 dn dib-l"> + <ul class="list ma0 pa0 dn dib-l" role="menu"> {{ range .Site.Menus.global }} <li class="f5 dib mr4" role="menuitem"> {{/* TODO: Create an "Global" active class to show which site one is currently at */}} diff --git a/docs/_vendor/modules.txt b/docs/_vendor/modules.txt index a0b2c4e28..b755ed7f6 100644 --- a/docs/_vendor/modules.txt +++ b/docs/_vendor/modules.txt @@ -1 +1 @@ -# github.com/gohugoio/gohugoioTheme v0.0.0-20211211134334-0fe25799bb58 +# github.com/gohugoio/gohugoioTheme v0.0.0-20220228085601-7cfbda06d135 diff --git a/docs/content/en/content-management/build-options.md b/docs/content/en/content-management/build-options.md index 93da7c421..c3f6f04c9 100644 --- a/docs/content/en/content-management/build-options.md +++ b/docs/content/en/content-management/build-options.md @@ -18,12 +18,12 @@ toc: true They are stored in a reserved Front Matter object named `_build` with the following defaults: -```yaml +{{< code-toggle >}} _build: render: always list: always publishResources: true -``` +{{< /code-toggle >}} #### render If `always`, the page will be treated as a published page, holding its dedicated output files (`index.html`, etc...) and permalink. diff --git a/docs/content/en/content-management/comments.md b/docs/content/en/content-management/comments.md index bbeb21ada..311f24c14 100644 --- a/docs/content/en/content-management/comments.md +++ b/docs/content/en/content-management/comments.md @@ -30,7 +30,7 @@ Hugo comes with all the code you need to load Disqus into your templates. Before Disqus comments require you set a single value in your [site's configuration file][configuration] like so: {{< code-toggle copy="false" >}} -disqusShortname = "yourdiscussshortname" +disqusShortname = "yourDisqusShortname" {{</ code-toggle >}} For many websites, this is enough configuration. However, you also have the option to set the following in the [front matter][] of a single content file: diff --git a/docs/content/en/content-management/diagrams.md b/docs/content/en/content-management/diagrams.md index 4e3f6164b..cfc0b3644 100644 --- a/docs/content/en/content-management/diagrams.md +++ b/docs/content/en/content-management/diagrams.md @@ -12,8 +12,68 @@ toc: true --- +{{< new-in "0.93.0" >}} + + +## GoAT Diagrams (Ascii) + +Hugo supports [GoAT](https://github.com/bep/goat) natively. This means that this code block: + +```` +```goat + . . . .--- 1 .-- 1 / 1 + / \ | | .---+ .-+ + + / \ .---+---. .--+--. | '--- 2 | '-- 2 / \ 2 + + + | | | | ---+ ---+ + + / \ / \ .-+-. .-+-. .+. .+. | .--- 3 | .-- 3 \ / 3 + / \ / \ | | | | | | | | '---+ '-+ + + 1 2 3 4 1 2 3 4 1 2 3 4 '--- 4 '-- 4 \ 4 + +``` +```` + +Will be rendered as: + +```goat + + . . . .--- 1 .-- 1 / 1 + / \ | | .---+ .-+ + + / \ .---+---. .--+--. | '--- 2 | '-- 2 / \ 2 + + + | | | | ---+ ---+ + + / \ / \ .-+-. .-+-. .+. .+. | .--- 3 | .-- 3 \ / 3 + / \ / \ | | | | | | | | '---+ '-+ + + 1 2 3 4 1 2 3 4 1 2 3 4 '--- 4 '-- 4 \ 4 +``` + + + + + ## Mermaid Diagrams +Hugo currently does not provide default templates for Mermaid diagrams. But you can easily add your own. One way to do it would be to create ` layouts/_default/_markup/render-codeblock-mermaid.html`: + + +```go-html-template +<div class="mermaid"> + {{- .Inner | safeHTML }} +</div> +{{ .Page.Store.Set "hasMermaid" true }} +``` + +And then include this snippet at the bottom of the content template (below `.Content`): + +```go-html-template +{{ if .Page.Store.Get "hasMermaid" }} + <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script> + <script> + mermaid.initialize({ startOnLoad: true }); + </script> +{{ end }} +``` + +With that you can use the `mermaid` language in Markdown code blocks: + ```mermaid sequenceDiagram participant Alice diff --git a/docs/content/en/hosting-and-deployment/deployment-with-nanobox.md b/docs/content/en/hosting-and-deployment/deployment-with-nanobox.md deleted file mode 100644 index 1ab77c401..000000000 --- a/docs/content/en/hosting-and-deployment/deployment-with-nanobox.md +++ /dev/null @@ -1,249 +0,0 @@ ---- -title: Host-Agnostic Deploys with Nanobox -linktitle: Host-Agnostic Deploys with Nanobox -description: Easily deploy Hugo to AWS, DigitalOcean, Google, Azure, and more... -date: 2017-08-24 -publishdate: 2017-08-24 -lastmod: 2017-08-24 -categories: [hosting and deployment] -keywords: [nanobox,deployment,hosting,aws,digitalocean,azure,google,linode] -authors: [Steve Domino] -menu: - docs: - parent: "hosting-and-deployment" - weight: 05 -weight: 05 -sections_weight: 05 -draft: false -aliases: [/tutorials/deployment-with-nanobox/] -toc: true ---- - - - -Nanobox provides an entire end-to-end workflow for developing and deploying applications. Using Nanobox to deploy also means you'll use it to develop your application. - -{{% note %}} -If you're already using Nanobox and just need deployment instructions, you can skip to [Deploying Hugo with Nanobox](#deploying-hugo-with-nanobox) -{{% /note %}} - - -## What You'll Need - -With Nanobox you don't need to worry about having Go or Hugo installed. They'll be installed as part of the development environment created for you. - -To get started you'll just need the following three items: - -* [A Nanobox Account](https://nanobox.io) - Signup is free -* [Nanobox Desktop](https://dashboard.nanobox.io/download) - The free desktop development tool -* An account with a hosting provider such as: - - [AWS](https://docs.nanobox.io/providers/hosting-accounts/aws/) - - [Google](https://docs.nanobox.io/providers/hosting-accounts/gcp/) - - [Azure](https://docs.nanobox.io/providers/hosting-accounts/azure/) - - [DigitalOcean](https://docs.nanobox.io/providers/hosting-accounts/digitalocean/) - - [Linode](https://docs.nanobox.io/providers/hosting-accounts/linode/) - - [More...](https://docs.nanobox.io/providers/hosting-accounts/) - - [Roll Your Own](https://docs.nanobox.io/providers/create/) - -### Before You Begin - -There are a few things to get out of the way before diving into the guide. To deploy, you'll need to make sure you have connected a host account to your Nanobox account, and launched a new application. - -#### Connect a Host Account - -Nanobox lets you choose where to host your application (AWS, DigitalOcean, Google, Azure, etc.). In the [Hosting Accounts](https://dashboard.nanobox.io/provider_accounts) section of your Nanobox dashboard [link your Nanobox account with your host](https://docs.nanobox.io/providers/hosting-accounts/). - -#### Launch a New Application on Nanobox - -[Launching a new app on Nanobox](https://docs.nanobox.io/workflow/launch-app/) is very simple. Navigate to [Launch New App](https://dashboard.nanobox.io/apps/new) in the dashboard, and follow the steps there. You'll be asked to name your app, and to select a host and region. - -With those out of the way you're ready to get started! - - -## Getting Started - -{{% note %}} -If you already have a functioning Hugo app, you can skip to [Configure Hugo to run with Nanobox](#configure-hugo-to-run-with-nanobox) -{{% /note %}} - -To get started, all you'll need is an empty project directory. Create a directory wherever you want your application to live and `cd` into it: - -`mkdir path/to/project && cd path/to/project` - -### Configure Hugo to run with Nanobox - -Nanobox uses a simple config file known as a [boxfile.yml](https://docs.nanobox.io/boxfile/) to describe your application's infrastructure. In the root of your project add the following `boxfile.yml`: - -{{< code file="boxfile.yml" >}} -run.config: - - # use the static engine - engine: static - engine.config: - - # tell the engine where to serve static assets from - rel_dir: public - - # enable file watching for live reload - fs_watch: true - - # install hugo - extra_steps: - - bash ./install.sh - -deploy.config: - - # generate site on deploy - extra_steps: - - hugo - -{{< /code >}} - -{{% note %}} -If you already have a functioning Hugo app, after adding the boxfile, you can skip to [Deploying Hugo with Nanobox](#deploying-hugo-with-nanobox). -{{% /note %}} - -### Installing Hugo - -Nanobox uses Docker to create instant, isolated, development environments. Because of this, you'll need to make sure that during development you have Hugo available. - -Do this by adding a custom install script at the root of your project that will install Hugo automatically for you: - -{{< code file="install.sh" >}} - -#!/bin/bash - -if [[ ! -f /data/bin/hugo ]]; then - cd /tmp - wget https://github.com/gohugoio/hugo/releases/download/v0.31.1/hugo_0.31.1_Linux-64bit.tar.gz - tar -xzf hugo_0.31.1_Linux-64bit.tar.gz - mv hugo /data/bin/hugo - cd - - rm -rf /tmp/* -fi - -{{< /code >}} - -{{% note %}} -If the install script fails during `nanobox run` you may need to make it executable with `chmod +x install.sh` -{{% /note %}} -{{% note %}} -Make sure to check the version of Hugo you have installed and update the install script to match. -{{% /note %}} - -### Generating a New Hugo App - -You'll generate your new application from inside the Nanobox VM (this is why you don't need to worry about having Go or Hugo installed). - -Run the following command to drop into a Nanobox console (inside the VM) where your codebase is mounted: - -``` -nanobox run -``` - - - -Once inside the console use the following steps to create a new Hugo application: - -``` -# cd into the /tmp dir to create an app -cd /tmp - -# generate the hugo app -hugo new site app - -# cd back into the /app dir -cd - - -# copy the generated app into the project -shopt -s dotglob -cp -a /tmp/app/* . -``` - -### Install a theme - -`cd` into the `themes` directory and clone the `nanobox-hugo-theme` repo: - -``` -cd themes -git clone https://github.com/sdomino/nanobox-hugo-theme -``` - -To use the theme *either* copy the entire `config.toml` that comes with the theme, or just add the theme to your existing `config.toml` - -``` -# copy the config.toml that comes with the theme -cp ./themes/nanobox-hugo-theme/config.toml config.toml - -# or, add it to your existing config.toml -theme = "nanobox-hugo-theme" -``` - -{{% note %}} -It is not intended that you use the `nanobox-hugo-theme` as your actual theme. It's simply a theme to start with and should be replaced. -{{% /note %}} - -### View Your App - -To view your application simply run the following command from a Nanobox console: - -``` -hugo server --bind="0.0.0.0" --baseUrl=$APP_IP -``` - - - -With that you should be able to visit your app at the given IP:1313 address - -{{% note %}} -You can [add a custom DNS alias](https://docs.nanobox.io/cli/dns/#add) to make it easier to access your app. Run `nanobox dns add local hugo.dev`. After starting your server, visit your app at [hugo.dev:1313](http://hugo.dev:1313) -{{% /note %}} - -### Develop, Develop, Develop - -{{% note %}} -IMPORTANT: One issue we are aware of, and actively investigating, is livereload. Currently, livereload does not work when developing Hugo applications with Nanobox. -{{% /note %}} - -With Hugo installed you're ready to go. Develop Hugo like you would normally (using all the generators, etc.). Once your app is ready to deploy, run `hugo` to generate your static assets and get ready to deploy! - - -## Deploying Hugo with Nanobox - -{{% note %}} -If you haven't already, make sure to [connect a hosting account](#connect-a-host-account) to your Nanobox account, and [launch a new application](#launch-a-new-application-on-nanobox) in the Dashboard. -{{% /note %}} - -To deploy your application to Nanobox you simply need to [link your local codebase](https://docs.nanobox.io/workflow/deploy-code/#add-your-live-app-as-a-remote) to an application you've created on Nanobox. That is done with the following command: - -``` -nanobox remote add <your-app-name> -``` - -{{% note %}} -You may be prompted to login using your ***Nanobox credentials*** at this time -{{% /note %}} - -### Stage Your Application (optional) - -Nanobox gives you the ability to [simulate your production environment locally](https://docs.nanobox.io/workflow/deploy-code/#preview-locally). While staging is optional it's always recommended, so there's no reason not to! - -To stage your app simply run: - -``` -nanobox deploy dry-run -``` - -Now visit your application with the IP address provided. - - - -### Deploy Your Application - -Once everything checks out and you're [ready to deploy](https://docs.nanobox.io/workflow/deploy-code/#deploy-to-production), simply run: - -``` -nanobox deploy -``` - -Within minutes you're Hugo app will be deployed to your host and humming along smoothly. That's it! diff --git a/docs/content/en/hosting-and-deployment/hosting-on-github.md b/docs/content/en/hosting-and-deployment/hosting-on-github.md index 675a696d3..ae30ce44a 100644 --- a/docs/content/en/hosting-and-deployment/hosting-on-github.md +++ b/docs/content/en/hosting-and-deployment/hosting-on-github.md @@ -34,14 +34,16 @@ There are two types of GitHub Pages: Please refer to the [GitHub Pages documentation][ghorgs] to decide which type of site you would like to create as it will determine which of the below methods to use. +## Branches for GitHub Actions + +The GitHub Actions used in these instructions pull source content from the `main` branch and then commit the generated content to the `gh-pages` branch. This applies regardless of what type of GitHub Pages you are using. This is a clean setup as your Hugo files are stored in one branch and your generated files are published into a separate branch. + ## GitHub User or Organization Pages As mentioned in the [GitHub Pages documentation][ghorgs], you can host a user/organization page in addition to project pages. Here are the key differences in GitHub Pages websites for Users and Organizations: -1. You must use a `<USERNAME>.github.io` to host your **generated** content -2. Content from the `main` branch will be used to publish your GitHub Pages site - -This is a much simpler setup as your Hugo files and generated content are published into two different repositories. +1. You must create a repository named `<USERNAME>.github.io` or `<ORGANIZATION>.github.io` to host your pages +2. By default, content from the `main` branch is used to publish GitHub Pages - rather than the `gh-pages` branch which is the default for project sites. However, the GitHub Actions in these instructions publish to the `gh-pages` branch. Therefore, if you are publishing Github pages for a user or organization, you will need to change the publishing branch to `gh-pages`. See the instructions later in this document. ## Build Hugo With GitHub Action diff --git a/docs/content/en/hugo-pipes/introduction.md b/docs/content/en/hugo-pipes/introduction.md index babf9cdb8..83d64d1d3 100755 --- a/docs/content/en/hugo-pipes/introduction.md +++ b/docs/content/en/hugo-pipes/introduction.md @@ -18,6 +18,23 @@ toc: true aliases: [/assets/] --- +## Find Resources in /assets + +This is about the global Resources mounted inside `/assets`. For the `.Page` scoped Resources, see [Page Resources](/content-management/page-resources/). + +Note that you can mount any directory into Hugo's virtual `assets` folder using the [Mount Configuration](/hugo-modules/configuration/#module-config-mounts). + +| Function | Description | +| ------------- | ------------- | +| `resources.Get` | Get locates the filename given in Hugo's assets files |