From: Bjørn Erik Pedersen Date: Wed, 1 Mar 2023 10:56:07 +0000 (+0100) Subject: Merge commit '336622d5e7afd9334cd2de7150d4f16bdf7c24f9' X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=97b010f52;p=brevno-suite%2Fhugo Merge commit '336622d5e7afd9334cd2de7150d4f16bdf7c24f9' --- 97b010f521e592b5fc29daace225476b64543643 diff --cc docs/content/en/about/security-model/index.md index 66cb15463,000000000..d4dacd9bf mode 100644,000000..100644 --- a/docs/content/en/about/security-model/index.md +++ b/docs/content/en/about/security-model/index.md @@@ -1,65 -1,0 +1,65 @@@ +--- +title: Hugo's Security Model +description: A summary of Hugo's security model. +date: 2019-10-01 +layout: single +keywords: ["Security", "Privacy"] +menu: + docs: + parent: "about" + weight: 4 +weight: 5 +sections_weight: 5 +aliases: [/security/] +toc: true +--- + +## Runtime Security + +Hugo produces static output, so once built, the runtime is the browser (assuming the output is HTML) and any server (API) that you integrate with. + +But when developing and building your site, the runtime is the `hugo` executable. Securing a runtime can be [a real challenge](https://blog.logrocket.com/how-to-protect-your-node-js-applications-from-malicious-dependencies-5f2e60ea08f9/). + +**Hugo's main approach is that of sandboxing and a security policy with strict defaults:** + +* Hugo has a virtual file system and only the main project (not third-party components) is allowed to mount directories or files outside the project root. +* Only the main project can walk symbolic links. +* User-defined components have read-only access to the filesystem. +* We shell out to some external binaries to support [Asciidoctor](/content-management/formats/#list-of-content-formats) and similar, but those binaries and their flags are predefined and disabled by default (see [Security Policy](#security-policy)). General functions to run arbitrary external OS commands have been [discussed](https://github.com/gohugoio/hugo/issues/796), but not implemented because of security concerns. + +## Security Policy + +Hugo has a built-in security policy that restricts access to [os/exec](https://pkg.go.dev/os/exec), remote communication and similar. + +The default configuration is listed below. Any build using features not in the allow list of the security policy will fail with a detailed message about what needs to be done. Most of these settings are allow lists (string or slice, [Regular Expressions](https://pkg.go.dev/regexp) or `none` which matches nothing). + +{{< code-toggle config="security" />}} + +Note that these and other config settings in Hugo can be overridden by the OS environment. If you want to block all remote HTTP fetching of data: + +```txt +HUGO_SECURITY_HTTP_URLS=none hugo +``` + +## Dependency Security + +Hugo is built as a static binary using [Go Modules](https://github.com/golang/go/wiki/Modules) to manage its dependencies. Go Modules have several safeguards, one of them being the `go.sum` file. This is a database of the expected cryptographic checksums of all of your dependencies, including transitive dependencies. + +[Hugo Modules](/hugo-modules/) is a feature built on top of the functionality of Go Modules. Like Go Modules, a Hugo project using Hugo Modules will have a `go.sum` file. We recommend that you commit this file to your version control system. The Hugo build will fail if there is a checksum mismatch, which would be an indication of [dependency tampering](https://julienrenaux.fr/2019/12/20/github-actions-security-risk/). + +## Web Application Security + +These are the security threats as defined by [OWASP](https://en.wikipedia.org/wiki/OWASP). + +For HTML output, this is the core security model: + + + +In short: + - Templates authors (you) are trusted, but the data you send in is not. ++Template and configuration authors (you) are trusted, but the data you send in is not. +This is why you sometimes need to use the _safe_ functions, such as `safeHTML`, to avoid escaping of data you know is safe. +There is one exception to the above, as noted in the documentation: If you enable inline shortcodes, you also say that the shortcodes and data handling in content files are trusted, as those macros are treated as pure text. +It may be worth adding that Hugo is a static site generator with no concept of dynamic user input. + +For content, the default Markdown renderer is [configured](/getting-started/configuration-markup) to remove or escape potentially unsafe content. This behavior can be reconfigured if you trust your content. diff --cc docs/content/en/getting-started/quick-start.md index 824d6030a,000000000..d49997570 mode 100644,000000..100644 --- a/docs/content/en/getting-started/quick-start.md +++ b/docs/content/en/getting-started/quick-start.md @@@ -1,219 -1,0 +1,225 @@@ +--- +title: Quick Start +linktitle: Quick Start +description: Learn to create a Hugo site in minutes. +categories: [getting started] +keywords: [quick start,usage] +menu: + docs: + parent: getting-started + weight: 10 +weight: 10 +toc: true +aliases: [/quickstart/,/overview/quickstart/] +--- + +In this tutorial you will: + +1. Create a site +2. Add content +3. Configure the site +4. Publish the site + +## Prerequisites + +Before you begin this tutorial you must: + +1. [Install Hugo] (the extended edition) +1. [Install Git] + +You must also be comfortable working from the command line. + +## Create a site + +### Commands + +{{% note %}} - If you are a Windows user, you must run these commands with [PowerShell]. You cannot use Windows Powershell, which is a different application, or the Command Prompt. You may also use a Linux shell if available. ++**If you are a Windows user:** ++ ++- Do not use the Command Prompt ++- Do not use Windows PowerShell ++- Run these commands from [PowerShell] or a Linux terminal such as WSL or Git Bash ++ ++PowerShell and Windows PowerShell are different applications. + +[PowerShell]: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows +{{% /note %}} + +Run these commands to create a Hugo site with the [Ananke] theme. The next section provides an explanation of each command. + +```text +hugo new site quickstart +cd quickstart +git init +git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke +echo "theme = 'ananke'" >> config.toml +hugo server +``` + +View your site at the URL displayed in your terminal. Press `Ctrl + C` to stop Hugo's development server. + +### Explanation of commands + +Create the [directory structure] for your project in the `quickstart` directory. + +```text +hugo new site quickstart +``` + +Change the current directory to the root of your project. + +```text +cd quickstart +``` + +Initialize an empty Git repository in the current directory. + +```text +git init +``` + +Clone the [Ananke] theme into the `themes` directory, adding it to your project as a [Git submodule]. + +```text +git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke +``` + +Append a line to the site configuration file, indicating the current theme. + +```text +echo "theme = 'ananke'" >> config.toml +``` + +Start Hugo's development server to view the site. + +```text +hugo server +``` + +Press `Ctrl + C` to stop Hugo's development server. + +## Add content + +Add a new page to your site. + +```text +hugo new posts/my-first-post.md +``` + +Hugo created the file in the `content/posts` directory. Open the file with your editor. + +```text +--- +title: "My First Post" +date: 2022-11-20T09:03:20-08:00 +draft: true +--- +``` + +Notice the `draft` value in the [front matter] is `true`. By default, Hugo does not publish draft content when you build the site. Learn more about [draft, future, and expired content]. + +Add some [markdown] to the body of the post, but do not change the `draft` value. + +[markdown]: https://commonmark.org/help/ + +```text +--- +title: "My First Post" +date: 2022-11-20T09:03:20-08:00 +draft: true +--- +## Introduction + +This is **bold** text, and this is *emphasized* text. + +Visit the [Hugo](https://gohugo.io) website! +``` + +Save the file, then start Hugo’s development server to view the site. You can run either of the following commands to include draft content. + +```text +hugo server --buildDrafts +hugo server -D +``` + +View your site at the URL displayed in your terminal. Keep the development server running as you continue to add and change content. + +{{% note %}} +Hugo's rendering engine conforms to the CommonMark [specification] for markdown. The CommonMark organization provides a useful [live testing tool] powered by the reference implementation. + +[live testing tool]: https://spec.commonmark.org/dingus/ +[specification]: https://spec.commonmark.org/ +{{% /note %}} + +## Configure the site + +With your editor, open the [site configuration] file (`config.toml`) in the root of your project. + +```text +baseURL = 'http://example.org/' +languageCode = 'en-us' +title = 'My New Hugo Site' +theme = 'ananke' +``` + +Make the following changes: + +1. Set the `baseURL` for your production site. This value must begin with the protocol and end with a slash, as shown above. + +2. Set the `languageCode` to your language and region. + +3. Set the `title` for your production site. + +Start Hugo's development server to see your changes, remembering to include draft content. + +```text +hugo server -D +``` + +{{% note %}} +Most theme authors provide configuration guidelines and options. Make sure to visit your theme's repository or documentation site for details. + +[The New Dynamic], authors of the Ananke theme, provide [documentation] for configuration and usage. They also provide a [demonstration site]. + +[demonstration site]: https://gohugo-ananke-theme-demo.netlify.app/ +[documentation]: https://github.com/theNewDynamic/gohugo-theme-ananke#readme +[The New Dynamic]: https://www.thenewdynamic.com/ +{{% /note %}} + +## Publish the site + +In this step you will _publish_ your site, but you will not _deploy_ it. + +When you _publish_ your site, Hugo creates the entire static site in the `public` directory in the root of your project. This includes the HTML files, and assets such as images, CSS files, and JavaScript files. + +When you publish your site, you typically do _not_ want to include [draft, future, or expired content]. The command is simple. + +```text +hugo +``` + +To learn how to _deploy_ your site, see the [hosting and deployment] section. + +## Ask for help + +Hugo's [forum] is an active community of users and developers who answer questions, share knowledge, and provide examples. A quick search of over 20,000 topics will often answer your question. Please be sure to read about [requesting help] before asking your first question. + +## Other resources + +For other resources to help you learn Hugo, including books and video tutorials, see the [external learning resources](/getting-started/external-learning-resources/) page. + +[Ananke]: https://github.com/theNewDynamic/gohugo-theme-ananke +[directory structure]: /getting-started/directory-structure +[draft, future, and expired content]: /getting-started/usage/#draft-future-and-expired-content +[draft, future, or expired content]: /getting-started/usage/#draft-future-and-expired-content +[external learning resources]:/getting-started/external-learning-resources/ +[forum]: https://discourse.gohugo.io/ +[forum]: https://discourse.gohugo.io/ +[front matter]: /content-management/front-matter +[Git submodule]: https://git-scm.com/book/en/v2/Git-Tools-Submodules +[hosting and deployment]: /hosting-and-deployment/ +[Install Git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git +[Install Hugo]: /installation/ +[Requesting Help]: https://discourse.gohugo.io/t/requesting-help/9132 +[Requesting Help]: https://discourse.gohugo.io/t/requesting-help/9132 +[site configuration]: /getting-started/configuration/ diff --cc docs/layouts/_default/_markup/render-codeblock-mermaid.html index 59641551c,000000000..94ea0cad0 mode 100644,000000..100644 --- a/docs/layouts/_default/_markup/render-codeblock-mermaid.html +++ b/docs/layouts/_default/_markup/render-codeblock-mermaid.html @@@ -1,4 -1,0 +1,4 @@@ -
++
 +  {{- .Inner | safeHTML }}
-
++ +{{ .Page.Store.Set "hasMermaid" true }} diff --cc docs/layouts/partials/hooks/before-body-end.html index fb7ae20ba,000000000..dab653508 mode 100644,000000..100644 --- a/docs/layouts/partials/hooks/before-body-end.html +++ b/docs/layouts/partials/hooks/before-body-end.html @@@ -1,6 -1,0 +1,7 @@@ +{{ if .Page.Store.Get "hasMermaid" }} - - +{{ end }}