diff --git a/.markdownlint.yaml b/.markdownlint.yaml index d9c2c5a67..ee0a28909 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -23,3 +23,4 @@ MD046: false MD049: false MD050: false MD053: false +MD055: false diff --git a/archetypes/showcase/index.md b/archetypes/showcase/index.md index 04d454575..cdd036722 100644 --- a/archetypes/showcase/index.md +++ b/archetypes/showcase/index.md @@ -20,7 +20,7 @@ byline: "[bep](https://github.com/bep), Hugo Lead" To complete this showcase: 1. Write the story about your site in this file. -2. Add a summary to the `bio.md` file in this folder. +2. Add a summary to the `bio.md` file in this directory. 3. Replace the `featured-template.png` with a screenshot of your site. You can rename it, but it must contain the word `featured`. 4. Create a new pull request in https://github.com/gohugoio/hugoDocs/pulls diff --git a/content/en/content-management/archetypes.md b/content/en/content-management/archetypes.md index acf101fda..2bea002a7 100644 --- a/content/en/content-management/archetypes.md +++ b/content/en/content-management/archetypes.md @@ -59,10 +59,10 @@ hugo new content posts/my-first-post.md The archetype lookup order is: -1. archetypes/posts.md -1. archetypes/default.md -1. themes/my-theme/archetypes/posts.md -1. themes/my-theme/archetypes/default.md +1. `archetypes/posts.md` +1. `archetypes/default.md` +1. `themes/my-theme/archetypes/posts.md` +1. `themes/my-theme/archetypes/default.md` If none of these exists, Hugo uses a built-in default archetype. diff --git a/content/en/content-management/content-adapters.md b/content/en/content-management/content-adapters.md index 90a2d6ba9..dd943aacb 100644 --- a/content/en/content-management/content-adapters.md +++ b/content/en/content-management/content-adapters.md @@ -17,7 +17,7 @@ toc: true A content adapter is a template that dynamically creates pages when building a site. For example, use a content adapter to create pages from a remote data source such as JSON, TOML, YAML, or XML. -Unlike templates that reside in the layouts directory, content adapters reside in the content directory, no more than one per directory per language. When a content adapter creates a page, the page's [logical path] will be relative to the content adapter. +Unlike templates that reside in the `layouts` directory, content adapters reside in the `content` directory, no more than one per directory per language. When a content adapter creates a page, the page's [logical path] will be relative to the content adapter. ```text content/ @@ -33,7 +33,7 @@ content/ └── _index.md ``` -Each content adapter is named _content.gotmpl and uses the same [syntax] as templates in the layouts directory. You can use any of the [template functions] within a content adapter, as well as the methods described below. +Each content adapter is named _content.gotmpl and uses the same [syntax] as templates in the `layouts` directory. You can use any of the [template functions] within a content adapter, as well as the methods described below. ## Methods diff --git a/content/en/content-management/cross-references.md b/content/en/content-management/cross-references.md index 124a3bf06..56f4c39e1 100644 --- a/content/en/content-management/cross-references.md +++ b/content/en/content-management/cross-references.md @@ -49,7 +49,7 @@ The pages can be referenced as follows: {{}} ``` -index.md can be reference either by its path or by its containing folder without the ending `/`. \_index.md can be referenced only by its containing folder: +`index.md` can be reference either by its path or by its containing directory without the ending `/`. `_index.md` can be referenced only by its containing directory: ```text {{}} <-- References /about/_index.md diff --git a/content/en/content-management/data-sources.md b/content/en/content-management/data-sources.md index c009fb7f3..07696ddad 100644 --- a/content/en/content-management/data-sources.md +++ b/content/en/content-management/data-sources.md @@ -16,7 +16,7 @@ Hugo can access and [unmarshal] local and remote data sources including CSV, JSO [unmarshal]: /getting-started/glossary/#unmarshal -A data source might be a file in the data directory, a [global resource], a [page resource], or a [remote resource]. +A data source might be a file in the `data` directory, a [global resource], a [page resource], or a [remote resource]. [global resource]: /getting-started/glossary/#global-resource [page resource]: /getting-started/glossary/#page-resource @@ -24,9 +24,9 @@ A data source might be a file in the data directory, a [global resource], a [pag ## Data directory -The data directory in the root of your project may contain one or more data files, in either a flat or nested tree. Hugo merges the data files to create a single data structure, accessible with the `Data` method on a `Site` object. +The `data` directory in the root of your project may contain one or more data files, in either a flat or nested tree. Hugo merges the data files to create a single data structure, accessible with the `Data` method on a `Site` object. -Hugo also merges data directories from themes and modules into this single data structure, where the data directory in the root of your project takes precedence. +Hugo also merges data directories from themes and modules into this single data structure, where the `data` directory in the root of your project takes precedence. {{% note %}} Hugo reads the combined data structure into memory and keeps it there for the entire build. For data that is infrequently accessed, use global or page resources instead. @@ -42,7 +42,7 @@ project/ ``` {{% note %}} -Do not place CSV files in the data directory. Access CSV files as page, global, or remote resources. +Do not place CSV files in the `data` directory. Access CSV files as page, global, or remote resources. {{% /note %}} See the documentation for the [`Data`] method on a `Site` object for details and examples. diff --git a/content/en/content-management/image-processing/index.md b/content/en/content-management/image-processing/index.md index 3cd02aa8d..058f1df4f 100644 --- a/content/en/content-management/image-processing/index.md +++ b/content/en/content-management/image-processing/index.md @@ -482,7 +482,7 @@ To control tag availability, change the `excludeFields` or `includeFields` setti ## Smart cropping of images -By default, Hugo uses the [Smartcrop] library when cropping images with the `Crop` or`Fill` methods. You can set the anchor point manually, but in most cases the `Smart` option will make a good choice. +By default, Hugo uses the [Smartcrop] library when cropping images with the `Crop` or `Fill` methods. You can set the anchor point manually, but in most cases the `Smart` option will make a good choice. Examples using the sunset image from above: diff --git a/content/en/content-management/multilingual.md b/content/en/content-management/multilingual.md index 165b2402e..b99c73cbe 100644 --- a/content/en/content-management/multilingual.md +++ b/content/en/content-management/multilingual.md @@ -80,7 +80,7 @@ defaultContentLanguageInSubdir : (`bool`) If `true`, Hugo renders the default language site in a subdirectory matching the `defaultContentLanguage`. Default is `false`. contentDir -: (`string`) The content directory for this language. Omit if [translating by file name]. +: (`string`) The `content` directory for this language. Omit if [translating by file name]. disabled : (`bool`) If `true`, Hugo will not render content for this language. Default is `false`. @@ -232,7 +232,7 @@ If a file has no language code, it will be assigned the default language. ### Translation by content directory -This system uses different content directories for each of the languages. Each language's content directory is set using the `contentDir` parameter. +This system uses different content directories for each of the languages. Each language's `content` directory is set using the `contentDir` parameter. {{< code-toggle file=hugo >}} languages: @@ -256,9 +256,9 @@ Considering the following example in conjunction with the configuration above: The first file is assigned the English language and is linked to the second. The second file is assigned the French language and is linked to the first. -Their language is __assigned__ according to the content directory they are __placed__ in. +Their language is __assigned__ according to the `content` directory they are __placed__ in. -By having the same **path and basename** (relative to their language content directory), the content pieces are __linked__ together as translated pages. +By having the same **path and basename** (relative to their language `content` directory), the content pieces are __linked__ together as translated pages. ### Bypassing default linking diff --git a/content/en/content-management/page-bundles.md b/content/en/content-management/page-bundles.md index b83bb0ba5..f4679cf70 100644 --- a/content/en/content-management/page-bundles.md +++ b/content/en/content-management/page-bundles.md @@ -30,13 +30,13 @@ The "about" page is a page bundle. It logically associates a resource with conte Page bundles are either _leaf bundles_ or _branch bundles_. leaf bundle -: A _leaf bundle_ is a directory that contains an index.md file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants. +: A _leaf bundle_ is a directory that contains an `index.md` file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants. branch bundle -: A _branch bundle_ is a directory that contains an _index.md file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without _index.md files are also branch bundles. This includes the home page. +: A _branch bundle_ is a directory that contains an `_index.md` file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without `_index.md` files are also branch bundles. This includes the home page. {{% note %}} -In the definitions above and the examples below, the extension of the index file depends on the [content format]. For example, use index.md for Markdown content, index.html for HTML content, index.adoc for AsciiDoc content, etc. +In the definitions above and the examples below, the extension of the index file depends on the [content format]. For example, use `index.md` for Markdown content, `index.html` for HTML content, `index.adoc` for AsciiDoc content, etc. [content format]: /getting-started/glossary/#content-format {{% /note %}} @@ -47,10 +47,10 @@ Page bundle characteristics vary by bundle type. | | Leaf bundle | Branch bundle | |---------------------|---------------------------------------------------------|---------------------------------------------------------| -| Index file | index.md | _index.md | -| Example | content/about/index.md | content/posts/_index.md | +| Index file | `index.md` | `_index.md` | +| Example | `content/about/index.md` | `content/posts/_index.md ` | | [Page kinds] | `page` | `home`, `section`, `taxonomy`, or `term` | -| Template types | [single] | [home], [section], [taxonomy], or [term] | +| Template types | [single] | [home], [section], [taxonomy], or [term] | | Descendant pages | None | Zero or more | | Resource location | Adjacent to the index file or in a nested subdirectory | Same as a leaf bundles, but excludes descendant bundles | | [Resource types] | `page`, `image`, `video`, etc. | all but `page` | @@ -65,7 +65,7 @@ Files with [resource type] `page` include content written in Markdown, HTML, Asc ## Leaf bundles -A _leaf bundle_ is a directory that contains an index.md file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants. +A _leaf bundle_ is a directory that contains an `index.md` file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants. ```text content/ @@ -111,12 +111,12 @@ another-leaf-bundle : This leaf bundle does not contain any page resources. {{% note %}} -Create leaf bundles at any depth within the content directory, but a leaf bundle may not contain another bundle. Leaf bundles do not have descendants. +Create leaf bundles at any depth within the `content` directory, but a leaf bundle may not contain another bundle. Leaf bundles do not have descendants. {{% /note %}} ## Branch bundles -A _branch bundle_ is a directory that contains an _index.md file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without _index.md files are also branch bundles. This includes the home page. +A _branch bundle_ is a directory that contains an `_index.md` file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without `_index.md` files are also branch bundles. This includes the home page. ```text content/ @@ -145,7 +145,7 @@ branch-bundle-2 : This branch bundle contains an index file and a leaf bundle. {{% note %}} -Create branch bundles at any depth within the content directory, but a leaf bundle may not contain another bundle. Leaf bundles do not have descendants. +Create branch bundles at any depth within the `content` directory, but a leaf bundle may not contain another bundle. Leaf bundles do not have descendants. {{% /note %}} diff --git a/content/en/content-management/related.md b/content/en/content-management/related.md index a9413fda7..08b6bdb55 100644 --- a/content/en/content-management/related.md +++ b/content/en/content-management/related.md @@ -80,7 +80,7 @@ weight = 80 {{< /code-toggle >}} * The `name` maps to a optional front matter slice attribute that can be used to link from the page level down to the fragment/heading level. -* If `applyFilter`is enabled, the `.HeadingsFiltered` on each page in the result will reflect the filtered headings. This is useful if you want to show the headings in the related content listing: +* If `applyFilter` is enabled, the `.HeadingsFiltered` on each page in the result will reflect the filtered headings. This is useful if you want to show the headings in the related content listing: ```go-html-template {{ $related := .Site.RegularPages.Related . | first 5 }} diff --git a/content/en/content-management/sections.md b/content/en/content-management/sections.md index 03655c90a..0d32d12ce 100644 --- a/content/en/content-management/sections.md +++ b/content/en/content-management/sections.md @@ -15,10 +15,10 @@ aliases: [/content/sections/] ## Overview -A section is a top-level content directory, or any content directory with an _index.md file. A content directory with an _index.md file is also known as a [branch bundle](/getting-started/glossary/#branch-bundle). Section templates receive one or more page [collections](/getting-started/glossary/#collection) in [context](/getting-started/glossary/#context). +A section is a top-level content directory, or any content directory with an `_index.md` file. A content directory with an `_index.md` file is also known as a [branch bundle](/getting-started/glossary/#branch-bundle). Section templates receive one or more page [collections](/getting-started/glossary/#collection) in [context](/getting-started/glossary/#context). {{% note %}} -Although top-level directories without _index.md files are sections, we recommend creating _index.md files in _all_ sections. +Although top-level directories without `_index.md` files are sections, we recommend creating `_index.md` files in _all_ sections. {{% /note %}} A typical site consists of one or more sections. For example: @@ -92,15 +92,15 @@ With the file structure from the [example above](#overview): Content directory|Section template :--|:-- -content/products|layouts/products/list.html -content/products/product-1|layouts/products/list.html -content/products/product-1/benefits|layouts/products/list.html +`content/products`|`layouts/products/list.html` +`content/products/product-1`|`layouts/products/list.html` +`content/products/product-1/benefits`|`layouts/products/list.html` Content directory|Single template :--|:-- -content/products|layouts/products/single.html -content/products/product-1|layouts/products/single.html -content/products/product-1/benefits|layouts/products/single.html +`content/products`|`layouts/products/single.html` +`content/products/product-1`|`layouts/products/single.html` +`content/products/product-1/benefits`|`layouts/products/single.html` If you need to use a different template for a subsection, specify `type` and/or `layout` in front matter. diff --git a/content/en/content-management/urls.md b/content/en/content-management/urls.md index 19538162c..6b8a217a6 100644 --- a/content/en/content-management/urls.md +++ b/content/en/content-management/urls.md @@ -473,7 +473,7 @@ Hugo renders alias files before rendering pages. A new page with the previous fi ### Customize -To override Hugo's embedded `alias` template, copy the [source code] to a file with the same name in the layouts directory. The template receives the following context: +To override Hugo's embedded `alias` template, copy the [source code] to a file with the same name in the `layouts` directory. The template receives the following context: Permalink : The link to the page being aliased. diff --git a/content/en/contribute/documentation.md b/content/en/contribute/documentation.md index d4e65c9e0..2f059dd40 100644 --- a/content/en/contribute/documentation.md +++ b/content/en/contribute/documentation.md @@ -69,8 +69,8 @@ In software documentation, passive voice is unavoidable in some cases. Please us No → With Hugo you can build a static site.\ Yes → Build a static site with Hugo. -No → This will cause Hugo to generate HTML files in the public directory.\ -Yes → Hugo generates HTML files in the public directory. +No → This will cause Hugo to generate HTML files in the `public` directory.\ +Yes → Hugo generates HTML files in the `public` directory. #### Use second person instead of third person @@ -105,10 +105,20 @@ For example: [functions]: /functions [methods]: /methods +## Directory names, file names, and file paths + +Enclose directory names, file names, and file paths within backticks, with the following exceptions: + +- Page titles +- Section headings (h1-h6) +- Definition list terms +- The description field in front matter + #### Miscellaneous Other guidelines to consider: +- Wrap directory names, file names, and file paths within a pair of backticks. - Do not place list items directly under a heading; include an introductory sentence or phrase before the list. - Avoid use of **bold** text. Use the [note shortcode] to draw attention to important content. - Do not place description terms (`dt`) within backticks unless required for syntactic clarity. diff --git a/content/en/functions/css/Sass.md b/content/en/functions/css/Sass.md index 31c4146b6..45f103e5d 100644 --- a/content/en/functions/css/Sass.md +++ b/content/en/functions/css/Sass.md @@ -125,7 +125,7 @@ Run `hugo env` to list the active transpilers. For [CI/CD] deployments (e.g., GitHub Pages, GitLab Pages, Netlify, etc.) you must edit the workflow to install Dart Sass before Hugo builds the site[^2]. Some providers allow you to use one of the package managers above, or you can download and extract one of the prebuilt binaries. -[^2]: You do not have to do this if (a) you have not modified the assets cache location, and (b) you have not set `useResourceCacheWhen` to `never` in your [site configuration], and (c) you add and commit your resources directory to your repository. +[^2]: You do not have to do this if (a) you have not modified the assets cache location, and (b) you have not set `useResourceCacheWhen` to `never` in your [site configuration], and (c) you add and commit your `resources` directory to your repository. #### GitHub Pages diff --git a/content/en/functions/css/TailwindCSS.md b/content/en/functions/css/TailwindCSS.md index 828ac9051..1b24fc207 100644 --- a/content/en/functions/css/TailwindCSS.md +++ b/content/en/functions/css/TailwindCSS.md @@ -80,7 +80,7 @@ Process the resource: {{ end }} ``` -The example above publishes the minified CSS file to public/css/main.css. +The example above publishes the minified CSS file to `public/css/main.css`. See [this repository] for more information about the integration with Tailwind CSS v4.0. diff --git a/content/en/functions/data/GetCSV.md b/content/en/functions/data/GetCSV.md index bef1bcba9..c17598ebe 100644 --- a/content/en/functions/data/GetCSV.md +++ b/content/en/functions/data/GetCSV.md @@ -46,7 +46,7 @@ Access the data with either of the following: {{% note %}} When working with local data, the file path is relative to the working directory. -You must not place CSV files in the project's data directory. +You must not place CSV files in the project's `data` directory. {{% /note %}} Access remote data with either of the following: diff --git a/content/en/functions/js/Batch.md b/content/en/functions/js/Batch.md index 4299654dc..35a7a621c 100644 --- a/content/en/functions/js/Batch.md +++ b/content/en/functions/js/Batch.md @@ -233,7 +233,7 @@ Hugo will, by default, first try to resolve any import in [assets](/hugo-pipes/i You can pass any object that implements [Resource.Get](/methods/page/resources/#get). Pass a slice to set multiple contexts. -The example above uses [`Resources.Mount`] to resolve a folder inside `assets` relative to the page bundle. +The example above uses [`Resources.Mount`] to resolve a directory inside `assets` relative to the page bundle. ### OptionsSetter diff --git a/content/en/functions/js/Build.md b/content/en/functions/js/Build.md index 0e5fd3c0a..4829f3b83 100644 --- a/content/en/functions/js/Build.md +++ b/content/en/functions/js/Build.md @@ -51,7 +51,7 @@ format {{% include "./_common/options.md" %}} -### Import JS code from /assets +### Import JS code from the assets directory `js.Build` has full support for the virtual union file system in [Hugo Modules](/hugo-modules/). You can see some simple examples in this [test project](https://github.com/gohugoio/hugoTestProjectJSModImports), but in short this means that you can do this: @@ -79,7 +79,7 @@ For other files (e.g. `JSON`, `CSS`) you need to use the relative path including import * as data from 'my/module/data.json'; ``` -Any imports in a file outside `/assets` or that does not resolve to a component inside `/assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`. +Any imports in a file outside `assets` or that does not resolve to a component inside `assets` will be resolved by [ESBuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`. Also note the new `params` option that can be passed from template to your JS files, e.g.: @@ -98,9 +98,9 @@ Hugo will, by default, generate a `assets/jsconfig.json` file that maps the impo Use the `js.Build` function to include Node.js dependencies. -Any imports in a file outside `/assets` or that does not resolve to a component inside `/assets` will be resolved by [esbuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`. +Any imports in a file outside `assets` or that does not resolve to a component inside `assets` will be resolved by [esbuild](https://esbuild.github.io/) with the **project directory** as the resolve directory (used as the starting point when looking for `node_modules` etc.). Also see [hugo mod npm pack](/commands/hugo_mod_npm_pack/). If you have any imported npm dependencies in your project, you need to make sure to run `npm install` before you run `hugo`. -The start directory for resolving npm packages (aka. packages that live inside a `node_modules` folder) is always the main project folder. +The start directory for resolving npm packages (aka. packages that live inside a `node_modules` directory) is always the main project directory. {{% note %}} If you're developing a theme/component that is supposed to be imported and depends on dependencies inside `package.json`, we recommend reading about [hugo mod npm pack](/commands/hugo_mod_npm_pack/), a tool to consolidate all the npm dependencies in a project. diff --git a/content/en/functions/js/_common/options.md b/content/en/functions/js/_common/options.md index df594df12..f92804fd0 100644 --- a/content/en/functions/js/_common/options.md +++ b/content/en/functions/js/_common/options.md @@ -14,7 +14,7 @@ And then in your JS file: import * as params from '@params'; ``` -Note that this is meant for small data sets, e.g. configuration settings. For larger data, please put/mount the files into `/assets` and import them directly. +Note that this is meant for small data sets, e.g. configuration settings. For larger data, please put/mount the files into `assets` and import them directly. minify : (`bool`)Let `js.Build` handle the minification. @@ -96,4 +96,4 @@ const App = () => <>Hello world!; const container = document.getElementById('app'); if (container) render(, container); -``` \ No newline at end of file +``` diff --git a/content/en/functions/lang/Translate.md b/content/en/functions/lang/Translate.md index 8c1b8f3f4..48c1345e2 100644 --- a/content/en/functions/lang/Translate.md +++ b/content/en/functions/lang/Translate.md @@ -31,7 +31,7 @@ To render placeholders for missing and fallback translations, set ## Translation tables -Create translation tables in the i18n directory, naming each file according to [RFC 5646]. Translation tables may be JSON, TOML, or YAML. For example: +Create translation tables in the `i18n` directory, naming each file according to [RFC 5646]. Translation tables may be JSON, TOML, or YAML. For example: ```text i18n/en.toml diff --git a/content/en/functions/resources/ByType.md b/content/en/functions/resources/ByType.md index dc3bc9c9c..ba9dcde0c 100644 --- a/content/en/functions/resources/ByType.md +++ b/content/en/functions/resources/ByType.md @@ -24,7 +24,7 @@ The [media type] is typically one of `image`, `text`, `audio`, `video`, or `appl ``` {{% note %}} -This function operates on global resources. A global resource is a file within the assets directory, or within any directory mounted to the assets directory. +This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory. For page resources, use the [`Resources.ByType`] method on a `Page` object. diff --git a/content/en/functions/resources/FromString.md b/content/en/functions/resources/FromString.md index a0be6497d..22663dc4b 100644 --- a/content/en/functions/resources/FromString.md +++ b/content/en/functions/resources/FromString.md @@ -19,7 +19,7 @@ Hugo publishes the resource to the target path when you call its [`Publish`], [` [`permalink`]: /methods/resource/permalink/ [`relpermalink`]: /methods/resource/relpermalink/ -Let's say you need to publish a file named "site.json" in the root of your public directory, containing the build date, the Hugo version used to build the site, and the date that the content was last modified. For example: +Let's say you need to publish a file named "site.json" in the root of your `public` directory, containing the build date, the Hugo version used to build the site, and the date that the content was last modified. For example: ```json { @@ -50,7 +50,7 @@ The example above: 1. Creates a map with the relevant key-value pairs using the [`dict`] function 2. Encodes the map as a JSON string using the [`jsonify`] function 3. Creates a resource from the JSON string using the `resources.FromString` function -4. Publishes the file to the root of the public directory using the resource's `.Publish` method +4. Publishes the file to the root of the `public` directory using the resource's `.Publish` method Combine `resources.FromString` with [`resources.ExecuteAsTemplate`] if your string contains template actions. Rewriting the example above: diff --git a/content/en/functions/resources/Get.md b/content/en/functions/resources/Get.md index 0678c4b0d..c6450febf 100644 --- a/content/en/functions/resources/Get.md +++ b/content/en/functions/resources/Get.md @@ -22,7 +22,7 @@ action: ``` {{% note %}} -This function operates on global resources. A global resource is a file within the assets directory, or within any directory mounted to the assets directory. +This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory. For page resources, use the [`Resources.Get`] method on a `Page` object. diff --git a/content/en/functions/resources/GetMatch.md b/content/en/functions/resources/GetMatch.md index 749867b41..7af2e7be8 100644 --- a/content/en/functions/resources/GetMatch.md +++ b/content/en/functions/resources/GetMatch.md @@ -22,7 +22,7 @@ action: ``` {{% note %}} -This function operates on global resources. A global resource is a file within the assets directory, or within any directory mounted to the assets directory. +This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory. For page resources, use the [`Resources.GetMatch`] method on a `Page` object. diff --git a/content/en/functions/resources/GetRemote.md b/content/en/functions/resources/GetRemote.md index 7ad56f19c..45da57739 100644 --- a/content/en/functions/resources/GetRemote.md +++ b/content/en/functions/resources/GetRemote.md @@ -103,7 +103,7 @@ Use the [`try`] statement to capture HTTP request errors. If you do not handle t [`try`]: /functions/go-template/try {{% note %}} -Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemtoe`returns nil. +Hugo does not classify an HTTP response with status code 404 as an error. In this case `resources.GetRemote` returns nil. {{% /note %}} ```go-html-template diff --git a/content/en/functions/resources/Match.md b/content/en/functions/resources/Match.md index 49c7e7df2..3e65555ba 100644 --- a/content/en/functions/resources/Match.md +++ b/content/en/functions/resources/Match.md @@ -22,7 +22,7 @@ action: ``` {{% note %}} -This function operates on global resources. A global resource is a file within the assets directory, or within any directory mounted to the assets directory. +This function operates on global resources. A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory. For page resources, use the [`Resources.Match`] method on a `Page` object. diff --git a/content/en/functions/resources/PostProcess.md b/content/en/functions/resources/PostProcess.md index e1f8e5f8e..82f02c9e5 100644 --- a/content/en/functions/resources/PostProcess.md +++ b/content/en/functions/resources/PostProcess.md @@ -79,7 +79,7 @@ module.exports = { {{% /note %}} Step 4 -: Enable creation of the `hugo_stats.json` file when building the site. If you are only using this for the production build, consider placing it below [config/production]. +: Enable creation of the `hugo_stats.json` file when building the site. If you are only using this for the production build, consider placing it below [`config/production`]. {{< code-toggle file=hugo >}} [build.buildStats] @@ -122,7 +122,7 @@ HUGO_ENVIRONMENT Default is `production` for `hugo` and `development` for `hugo server`. HUGO_PUBLISHDIR -: The absolute path to the publish directory (the `public` directory). Note that the value will always point to a directory on disk even when running `hugo server` in memory mode. If you write to this folder from PostCSS when running the server, you could run the server with one of these flags: +: The absolute path to the publish directory (the `public` directory). Note that the value will always point to a directory on disk even when running `hugo server` in memory mode. If you write to this directory from PostCSS when running the server, you could run the server with one of these flags: ```sh hugo server --renderToDisk @@ -153,6 +153,6 @@ You cannot manipulate the values returned from the resource’s methods. For exa [node.js]: https://nodejs.org/en/download [supported file name]: https://github.com/postcss/postcss-load-config#usage -[config/production]: /getting-started/configuration/#configuration-directory +[`config/production`]: /getting-started/configuration/#configuration-directory [configure build]: /getting-started/configuration/#configure-build [purgecss]: https://github.com/FullHuman/purgecss#readme diff --git a/content/en/functions/resources/ToCSS.md b/content/en/functions/resources/ToCSS.md index b4acda579..b944c72aa 100644 --- a/content/en/functions/resources/ToCSS.md +++ b/content/en/functions/resources/ToCSS.md @@ -126,7 +126,7 @@ Run `hugo env` to list the active transpilers. For [CI/CD] deployments (e.g., GitHub Pages, GitLab Pages, Netlify, etc.) you must edit the workflow to install Dart Sass before Hugo builds the site[^2]. Some providers allow you to use one of the package managers above, or you can download and extract one of the prebuilt binaries. -[^2]: You do not have to do this if (a) you have not modified the assets cache location, and (b) you have not set `useResourceCacheWhen` to `never` in your [site configuration], and (c) you add and commit your resources directory to your repository. +[^2]: You do not have to do this if (a) you have not modified the assets cache location, and (b) you have not set `useResourceCacheWhen` to `never` in your [site configuration], and (c) you add and commit your `resources` directory to your repository. #### GitHub Pages diff --git a/content/en/functions/transform/Unmarshal.md b/content/en/functions/transform/Unmarshal.md index 20505d1b6..6b417c357 100644 --- a/content/en/functions/transform/Unmarshal.md +++ b/content/en/functions/transform/Unmarshal.md @@ -37,7 +37,7 @@ Use the `transform.Unmarshal` function with global, page, and remote resources. ### Global resource -A global resource is a file within the assets directory, or within any directory mounted to the assets directory. +A global resource is a file within the `assets` directory, or within any directory mounted to the `assets` directory. ```text assets/ diff --git a/content/en/functions/urls/Ref.md b/content/en/functions/urls/Ref.md index 6cd97f030..d8fe6f26c 100644 --- a/content/en/functions/urls/Ref.md +++ b/content/en/functions/urls/Ref.md @@ -35,7 +35,7 @@ The second argument is a path to a page, with or without a file extension, with Instead of specifying a path, you can also provide an options map: path -: (`string`) The path to the page, relative to the content directory. Required. +: (`string`) The path to the page, relative to the `content` directory. Required. lang : (`string`) The language (site) to search for the page. Default is the current language. Optional. diff --git a/content/en/functions/urls/RelRef.md b/content/en/functions/urls/RelRef.md index 6b45b2131..74e1b5650 100644 --- a/content/en/functions/urls/RelRef.md +++ b/content/en/functions/urls/RelRef.md @@ -42,7 +42,7 @@ Code|baseURL|Permalink Instead of specifying a path, you can also provide an options map: path -: (`string`) The path to the page, relative to the content directory. Required. +: (`string`) The path to the page, relative to the `content` directory. Required. lang : (`string`) The language (site) to search for the page. Default is the current language. Optional. diff --git a/content/en/getting-started/configuration-build.md b/content/en/getting-started/configuration-build.md index cc64b51d7..91a19a9be 100644 --- a/content/en/getting-started/configuration-build.md +++ b/content/en/getting-started/configuration-build.md @@ -26,7 +26,7 @@ See [Configure Cache Busters](#configure-cache-busters). #### noJSConfigInAssets -(`bool`) If `true`, turns off writing a `jsconfig.json` into your `/assets` folder with mapping of imports from running [js.Build](/hugo-pipes/js). This file is intended to help with intellisense/navigation inside code editors such as [VS Code](https://code.visualstudio.com/). Note that if you do not use `js.Build`, no file will be written. +(`bool`) If `true`, turns off writing a `jsconfig.json` into your `assets` directory with mapping of imports from running [js.Build](/hugo-pipes/js). This file is intended to help with intellisense/navigation inside code editors such as [VS Code](https://code.visualstudio.com/). Note that if you do not use `js.Build`, no file will be written. #### useResourceCacheWhen @@ -78,11 +78,11 @@ If `enable` is set to `true`, creates a `hugo_stats.json` file in the root of yo Exclude `class` attributes, `id` attributes, or tags from `hugo_stats.json` with the `disableClasses`, `disableIDs`, and `disableTags` keys. {{% note %}} -Given that CSS purging is typically limited to production builds, place the `buildStats` object below [config/production]. +Given that CSS purging is typically limited to production builds, place the `buildStats` object below [`config/production`]. -[config/production]: /getting-started/configuration/#configuration-directory +[`config/production`]: /getting-started/configuration/#configuration-directory Built for speed, there may be "false positive" detections (e.g., HTML elements that are not HTML elements) while parsing the published site. These "false positives" are infrequent and inconsequential. {{% /note %}} -Due to the nature of partial server builds, new HTML entities are added while the server is running, but old values will not be removed until you restart the server or run a regular `hugo` build. \ No newline at end of file +Due to the nature of partial server builds, new HTML entities are added while the server is running, but old values will not be removed until you restart the server or run a regular `hugo` build. diff --git a/content/en/getting-started/directory-structure.md b/content/en/getting-started/directory-structure.md index 2331d8838..823db20ff 100644 --- a/content/en/getting-started/directory-structure.md +++ b/content/en/getting-started/directory-structure.md @@ -104,7 +104,7 @@ The `i18n` directory contains translation tables for multilingual sites. See&nbs ###### layouts -The layouts directory contains templates to transform content, data, and resources into a complete website. See [details](/templates/). +The `layouts` directory contains templates to transform content, data, and resources into a complete website. See [details](/templates/). ###### public @@ -116,7 +116,7 @@ The `resources` directory contains cached output from Hugo's asset pipelines, ge ###### static -The `static` directory contains files that will be copied to the public directory when you build your site. For example: `favicon.ico`, `robots.txt`, and files that verify site ownership. Before the introduction of [page bundles](/getting-started/glossary/#page-bundle) and [asset pipelines](/hugo-pipes/introduction/), the `static` directory was also used for images, CSS, and JavaScript. +The `static` directory contains files that will be copied to the `public` directory when you build your site. For example: `favicon.ico`, `robots.txt`, and files that verify site ownership. Before the introduction of [page bundles](/getting-started/glossary/#page-bundle) and [asset pipelines](/hugo-pipes/introduction/), the `static` directory was also used for images, CSS, and JavaScript. ###### themes @@ -186,7 +186,7 @@ home/ ``` {{% note %}} -When two or more files have the same path, the order of precedence follows the order of the mounts. For example, if the shared content directory contains `books/book-1.md`, it will be ignored because the project's content directory was mounted first. +When two or more files have the same path, the order of precedence follows the order of the mounts. For example, if the shared content directory contains `books/book-1.md`, it will be ignored because the project's `content` directory was mounted first. {{% /note %}} You can mount directories to `archetypes`, `assets`, `content`, `data`, `i18n`, `layouts`, and `static`. See [details](/hugo-modules/configuration/#module-configuration-mounts). diff --git a/content/en/getting-started/glossary.md b/content/en/getting-started/glossary.md index 117f6f1aa..1b4fb2981 100644 --- a/content/en/getting-started/glossary.md +++ b/content/en/getting-started/glossary.md @@ -60,7 +60,7 @@ A data type with two possible values, either `true` or `false`. ###### branch bundle -A directory that contains an _index.md file and zero or more [resources](#resource). Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without _index.md files are also branch bundles. This includes the home page. See [details](/content-management/page-bundles/). +A directory that contains an `_index.md` file and zero or more [resources](#resource). Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without `_index.md` files are also branch bundles. This includes the home page. See [details](/content-management/page-bundles/). ###### build @@ -100,7 +100,7 @@ A markup language for creating content. Typically Markdown, but may also be HTML ###### content type -A classification of content inferred from the top-level directory name or the `type` set in [front matter](#front-matter). Pages in the root of the content directory, including the home page, are of type "page". Accessed via `.Page.Type` in [templates](#template). See [details](/content-management/types/). +A classification of content inferred from the top-level directory name or the `type` set in [front matter](#front-matter). Pages in the root of the `content` directory, including the home page, are of type "page". Accessed via `.Page.Type` in [templates](#template). See [details](/content-management/types/). ###### content view @@ -158,7 +158,7 @@ Used within a [template action](#template-action), a function takes one or more ###### global resource -A file within the assets directory, or within any directory [mounted](/hugo-modules/configuration/#module-configuration-mounts) to the assets directory. Capture one or more global resources using the [`resources.Get`], [`resources.GetMatch`], [`resources.Match`], or [`resources.ByType`] functions. +A file within the `assets` directory, or within any directory [mounted](/hugo-modules/configuration/#module-configuration-mounts) to the `assets` directory. Capture one or more global resources using the [`resources.Get`], [`resources.GetMatch`], [`resources.Match`], or [`resources.ByType`] functions. [`resources.Get`]: /functions/resources/get/ [`resources.GetMatch`]: /functions/resources/getmatch/ @@ -227,7 +227,7 @@ Adaptation of a site to meet language and regional requirements. This includes t {{< new-in 0.123.0 >}} -A page or page resource identifier derived from the file path, excluding its extension and language identifier. This value is neither a file path nor a URL. Starting with a file path relative to the content directory, Hugo determines the logical path by stripping the file extension and language identifier, converting to lower case, then replacing spaces with hyphens. {{% comment %}}{{% /comment %}} See [examples](/methods/page/path/#examples). +A page or page resource identifier derived from the file path, excluding its extension and language identifier. This value is neither a file path nor a URL. Starting with a file path relative to the `content` directory, Hugo determines the logical path by stripping the file extension and language identifier, converting to lower case, then replacing spaces with hyphens. {{% comment %}}{{% /comment %}} See [examples](/methods/page/path/#examples). ###### map @@ -377,7 +377,7 @@ Conceptually, a [map](#map) with [methods](#method) to set, get, update, and del ###### section -A top-level content directory, or any content directory with an _index.md file. A content directory with an _index.md file is also known as a [branch bundle](/getting-started/glossary/#branch-bundle). Section templates receive one or more page [collections](#collection) in [context](#context). See [details](/content-management/sections/). +A top-level content directory, or any content directory with an `_index.md` file. A content directory with an `_index.md` file is also known as a [branch bundle](/getting-started/glossary/#branch-bundle). Section templates receive one or more page [collections](#collection) in [context](#context). See [details](/content-management/sections/). ###### section page @@ -421,7 +421,7 @@ Content with the "taxonomy" [page kind](#page-kind). Typically a listing of [ter ###### template -A file with [template actions](#template-action), located within the layouts directory of a project, theme, or module. See [details](/templates/). +A file with [template actions](#template-action), located within the `layouts` directory of a project, theme, or module. See [details](/templates/). ###### template action diff --git a/content/en/getting-started/usage.md b/content/en/getting-started/usage.md index dbbccc6f0..08a47d5e7 100644 --- a/content/en/getting-started/usage.md +++ b/content/en/getting-started/usage.md @@ -53,7 +53,7 @@ The [`hugo`] command builds your site, publishing the files to the `public` dire {{% note %}} Hugo does not clear the `public` directory before building your site. Existing files are overwritten, but not deleted. This behavior is intentional to prevent the inadvertent removal of files that you may have added to the `public` directory after the build. -Depending on your needs, you may wish to manually clear the contents of the public directory before every build. +Depending on your needs, you may wish to manually clear the contents of the `public` directory before every build. {{% /note %}} ## Draft, future, and expired content @@ -124,7 +124,7 @@ hugo server --navigateToChanged ## Deploy your site {{% note %}} -As noted above, Hugo does not clear the public directory before building your site. Manually clear the contents of the public directory before each build to remove draft, expired, and future content. +As noted above, Hugo does not clear the `public` directory before building your site. Manually clear the contents of the `public` directory before each build to remove draft, expired, and future content. {{% /note %}} When you are ready to deploy your site, run: @@ -133,7 +133,7 @@ When you are ready to deploy your site, run: hugo ``` -This builds your site, publishing the files to the public directory. The directory structure will look something like this: +This builds your site, publishing the files to the `public` directory. The directory structure will look something like this: ```text public/ @@ -159,7 +159,7 @@ Most of our users deploy their sites using a CI/CD workflow, where a push[^1] to Learn more in the [hosting and deployment] section. -[^1]: The Git repository contains the entire project directory, typically excluding the public directory because the site is built _after_ the push. +[^1]: The Git repository contains the entire project directory, typically excluding the `public` directory because the site is built _after_ the push. [`--destination`]: /commands/hugo/#options [`hugo server`]: /commands/hugo_server/ diff --git a/content/en/hosting-and-deployment/deployment-with-rsync.md b/content/en/hosting-and-deployment/deployment-with-rsync.md index 06f250b37..8fb428686 100644 --- a/content/en/hosting-and-deployment/deployment-with-rsync.md +++ b/content/en/hosting-and-deployment/deployment-with-rsync.md @@ -91,7 +91,7 @@ USER=my-user HOST=my-server.com DIR=my/directory/to/topologix.fr/ # the directory where your website files should go -hugo && rsync -avz --delete public/ ${USER}@${HOST}:~/${DIR} # this will delete everything on the server that's not in the local public folder +hugo && rsync -avz --delete public/ ${USER}@${HOST}:~/${DIR} # this will delete everything on the server that's not in the local public directory exit 0 ``` diff --git a/content/en/hosting-and-deployment/hugo-deploy.md b/content/en/hosting-and-deployment/hugo-deploy.md index ea42da39f..4abcba73f 100644 --- a/content/en/hosting-and-deployment/hugo-deploy.md +++ b/content/en/hosting-and-deployment/hugo-deploy.md @@ -175,8 +175,8 @@ URL = "" # Azure Blob Storage; see https://gocloud.dev/howto/blob/#azure #URL = "azblob://$web" -# You can use a "prefix=" query parameter to target a subfolder of the bucket: -#URL = "gs://?prefix=a/subfolder/" +# You can use a "prefix=" query parameter to target a subdirectory of the bucket: +#URL = "gs://?prefix=a/subdirectory/" # If you are using a CloudFront CDN, deploy will invalidate the cache as needed. #cloudFrontDistributionID = "" diff --git a/content/en/hugo-modules/_index.md b/content/en/hugo-modules/_index.md index 01fc21e50..87ce33a6c 100644 --- a/content/en/hugo-modules/_index.md +++ b/content/en/hugo-modules/_index.md @@ -25,5 +25,5 @@ Hugo Modules are powered by Go Modules. For more information about Go Modules, s Some example projects: -- [https://github.com/bep/docuapi](https://github.com/bep/docuapi) is a theme that has been ported to Hugo Modules while testing this feature. It is a good example of a non-Hugo-project mounted into Hugo’s folder structure. It even shows a JS Bundler implementation in regular Go templates. +- [https://github.com/bep/docuapi](https://github.com/bep/docuapi) is a theme that has been ported to Hugo Modules while testing this feature. It is a good example of a non-Hugo-project mounted into Hugo's directory structure. It even shows a JS Bundler implementation in regular Go templates. - [https://github.com/bep/my-modular-site](https://github.com/bep/my-modular-site) is a very simple site used for testing. diff --git a/content/en/hugo-modules/configuration.md b/content/en/hugo-modules/configuration.md index cd51614b6..c6d8c3900 100644 --- a/content/en/hugo-modules/configuration.md +++ b/content/en/hugo-modules/configuration.md @@ -91,7 +91,7 @@ extended {{< /code-toggle >}} path -: Can be either a valid Go Module module path, e.g. `github.com/gohugoio/myShortcodes`, or the directory name for the module as stored in your themes folder. +: Can be either a valid Go Module module path, e.g. `github.com/gohugoio/myShortcodes`, or the directory name for the module as stored in your `themes` directory. ignoreConfig : If enabled, any module configuration file, e.g. `hugo.toml`, will not be loaded. Note that this will also stop the loading of any transitive module dependencies. @@ -103,7 +103,7 @@ disable : Set to `true` to disable the module while keeping any version info in the `go.*` files. noMounts -: Do not mount any folder in this import. +: Do not mount any directory in this import. noVendor : Never vendor this import (only allowed in main project). @@ -151,7 +151,7 @@ source : (`string`) The source directory of the mount. For the main project, this can be either project-relative or absolute. For other modules it must be project-relative. target -: (`string`) Where it should be mounted into Hugo's virtual filesystem. It must start with one of Hugo's component folders: `static`, `content`, `layouts`, `data`, `assets`, `i18n`, or `archetypes`. E.g. `content/blog`. +: (`string`) Where it should be mounted into Hugo's virtual filesystem. It must start with one of Hugo's component directories: `static`, `content`, `layouts`, `data`, `assets`, `i18n`, or `archetypes`. E.g. `content/blog`. disableWatch {{< new-in 0.128.0 >}} diff --git a/content/en/hugo-modules/theme-components.md b/content/en/hugo-modules/theme-components.md index 947a0ff79..9e52620ce 100644 --- a/content/en/hugo-modules/theme-components.md +++ b/content/en/hugo-modules/theme-components.md @@ -32,7 +32,7 @@ Hugo uses two different algorithms to merge the file systems, depending on the f * For `i18n` and `data` files, Hugo merges deeply using the translation ID and data key inside the files. * For `static`, `layouts` (templates), and `archetypes` files, these are merged on file level. So the left-most file will be chosen. -The name used in the `theme` definition above must match a folder in `/your-site/themes`, e.g. `/your-site/themes/my-shortcodes`. There are plans to improve on this and get a URL scheme so this can be resolved automatically. +The name used in the `theme` definition above must match a directory in `/your-site/themes`, e.g. `/your-site/themes/my-shortcodes`. There are plans to improve on this and get a URL scheme so this can be resolved automatically. Also note that a component that is part of a theme can have its own configuration file, e.g. `hugo.toml`. There are currently some restrictions to what a theme component can configure: diff --git a/content/en/hugo-modules/use-modules.md b/content/en/hugo-modules/use-modules.md index d14379a10..0b623678a 100644 --- a/content/en/hugo-modules/use-modules.md +++ b/content/en/hugo-modules/use-modules.md @@ -107,12 +107,12 @@ Also see the [CLI Doc](/commands/hugo_mod_graph/). ## Vendor your modules -`hugo mod vendor` will write all the module dependencies to a `_vendor` folder, which will then be used for all subsequent builds. +`hugo mod vendor` will write all the module dependencies to a `_vendor` directory, which will then be used for all subsequent builds. Note that: * You can run `hugo mod vendor` on any level in the module tree. -* Vendoring will not store modules stored in your `themes` folder. +* Vendoring will not store modules stored in your `themes` directory. * Most commands accept a `--ignoreVendorPaths` flag, which will then not use the vendored modules in `_vendor` for the module paths matching the [Glob](https://github.com/gobwas/glob) pattern given. Also see the [CLI Doc](/commands/hugo_mod_vendor/). diff --git a/content/en/hugo-pipes/introduction.md b/content/en/hugo-pipes/introduction.md index 0e6430311..645171153 100755 --- a/content/en/hugo-pipes/introduction.md +++ b/content/en/hugo-pipes/introduction.md @@ -18,7 +18,7 @@ aliases: [/assets/] This is about global and remote resources. global resource -: A file within the assets directory, or within any directory [mounted] to the assets directory. +: A file within the `assets` directory, or within any directory [mounted] to the `assets` directory. remote resource : A file on a remote server, accessible via HTTP or HTTPS. @@ -51,7 +51,7 @@ See the [`resources.Copy`](/functions/resources/copy/) function. ## Asset directory -Asset files must be stored in the asset directory. This is `/assets` by default, but can be configured via the configuration file's `assetDir` key. +Asset files must be stored in the asset directory. This is `assets` by default, but can be configured via the configuration file's `assetDir` key. ## Asset publishing diff --git a/content/en/hugo-pipes/postprocess.md b/content/en/hugo-pipes/postprocess.md index 57c71e8ab..0e3b040ab 100755 --- a/content/en/hugo-pipes/postprocess.md +++ b/content/en/hugo-pipes/postprocess.md @@ -37,7 +37,7 @@ There are currently two limitations to this: There are several ways to set up CSS purging with PostCSS in Hugo. If you have a simple project, you should consider going the simpler route and drop the use of `resources.PostProcess` and just extract keywords from the templates. See the [Tailwind documentation](https://tailwindcss.com/docs/controlling-file-size/#app) for some examples. {{% /note %}} -The below configuration will write a `hugo_stats.json` file to the project root as part of the build. If you're only using this for the production build, you should consider placing it below [config/production](/getting-started/configuration/#configuration-directory). +The below configuration will write a `hugo_stats.json` file to the project root as part of the build. If you're only using this for the production build, you should consider placing it below [`config/production`](/getting-started/configuration/#configuration-directory). {{< code-toggle file=hugo >}} [build.buildStats] @@ -88,7 +88,7 @@ HUGO_ENVIRONMENT : The value e.g. set with `hugo -e production` (defaults to `production` for `hugo` and `development` for `hugo server`). HUGO_PUBLISHDIR -: The absolute path to the publish directory (the `public` directory). Note that the value will always point to a directory on disk even when running `hugo server` in memory mode. If you write to this folder from PostCSS when running the server, you could run the server with one of these flags: +: The absolute path to the publish directory (the `public` directory). Note that the value will always point to a directory on disk even when running `hugo server` in memory mode. If you write to this directory from PostCSS when running the server, you could run the server with one of these flags: ```sh hugo server --renderToDisk diff --git a/content/en/hugo-pipes/transpile-sass-to-css.md b/content/en/hugo-pipes/transpile-sass-to-css.md index c0382790a..a7f790c8a 100644 --- a/content/en/hugo-pipes/transpile-sass-to-css.md +++ b/content/en/hugo-pipes/transpile-sass-to-css.md @@ -117,7 +117,7 @@ Run `hugo env` to list the active transpilers. For [CI/CD] deployments (e.g., GitHub Pages, GitLab Pages, Netlify, etc.) you must edit the workflow to install Dart Sass before Hugo builds the site[^2]. Some providers allow you to use one of the package managers above, or you can download and extract one of the prebuilt binaries. -[^2]: You do not have to do this if (a) you have not modified the assets cache location, and (b) you have not set `useResourceCacheWhen` to `never` in your [site configuration], and (c) you add and commit your resources directory to your repository. +[^2]: You do not have to do this if (a) you have not modified the assets cache location, and (b) you have not set `useResourceCacheWhen` to `never` in your [site configuration], and (c) you add and commit your `resources` directory to your repository. #### GitHub Pages diff --git a/content/en/methods/page/File.md b/content/en/methods/page/File.md index d59171577..5d20e3c95 100644 --- a/content/en/methods/page/File.md +++ b/content/en/methods/page/File.md @@ -12,7 +12,7 @@ toc: true By default, not all pages are backed by a file, including top level [section] pages, [taxonomy] pages, and [term] pages. By definition, you cannot retrieve file information when the file does not exist. -To back one of the pages above with a file, create an _index.md file in the corresponding directory. For example: +To back one of the pages above with a file, create an `_index.md` file in the corresponding directory. For example: ```text content/ diff --git a/content/en/methods/page/GetPage.md b/content/en/methods/page/GetPage.md index 3d8a9a89b..7c71c5afa 100644 --- a/content/en/methods/page/GetPage.md +++ b/content/en/methods/page/GetPage.md @@ -15,7 +15,7 @@ The `GetPage` method is also available on a `Site` object. See [details]. [details]: /methods/site/getpage/ -When using the `GetPage` method on the `Page` object, specify a path relative to the current directory or relative to the content directory. +When using the `GetPage` method on the `Page` object, specify a path relative to the current directory or relative to the `content` directory. If Hugo cannot resolve the path to a page, the method returns nil. If the path is ambiguous, Hugo throws an error and fails the build. diff --git a/content/en/methods/page/IsTranslated.md b/content/en/methods/page/IsTranslated.md index 6a8f3f69e..47019a52c 100644 --- a/content/en/methods/page/IsTranslated.md +++ b/content/en/methods/page/IsTranslated.md @@ -46,13 +46,13 @@ content/ └── _index.md ``` -When rendering content/en/books/book-1.md: +When rendering `content/en/books/book-1.md`: ```go-html-template {{ .IsTranslated }} → true ``` -When rendering content/en/books/book-2.md: +When rendering `content/en/books/book-2.md`: ```go-html-template {{ .IsTranslated }} → false diff --git a/content/en/methods/page/Pages.md b/content/en/methods/page/Pages.md index d446292e2..1ea6f97dc 100644 --- a/content/en/methods/page/Pages.md +++ b/content/en/methods/page/Pages.md @@ -70,7 +70,7 @@ When rendering lesson-2, the `Pages` method returns: lessons/lesson-2/resources/task-list.md lessons/lesson-2/resources/worksheet.md -In the last example, the collection includes pages in the resources subdirectory. That directory is not a [section]---it does not contain an _index.md file. Its contents are part of the lesson-2 section. +In the last example, the collection includes pages in the resources subdirectory. That directory is not a [section]---it does not contain an `_index.md` file. Its contents are part of the lesson-2 section. {{% note %}} When used with a `Site` object, the `Pages` method recursively returns all pages within the site. See [details]. diff --git a/content/en/methods/page/Path.md b/content/en/methods/page/Path.md index 0082947f7..a0ec6ceba 100644 --- a/content/en/methods/page/Path.md +++ b/content/en/methods/page/Path.md @@ -33,7 +33,7 @@ The meaning of, and value returned by, the `Path` method on a `Page` object chan [v0.123.0]: https://github.com/gohugoio/hugo/releases/tag/v0.123.0 {{% /note %}} -To determine the logical path for pages backed by a file, Hugo starts with the file path, relative to the content directory, and then: +To determine the logical path for pages backed by a file, Hugo starts with the file path, relative to the `content` directory, and then: 1. Strips the file extension 2. Strips the language identifier diff --git a/content/en/methods/page/Ref.md b/content/en/methods/page/Ref.md index e3c5569a4..e0d42424d 100644 --- a/content/en/methods/page/Ref.md +++ b/content/en/methods/page/Ref.md @@ -15,7 +15,7 @@ action: The map of option contains: path -: (`string`) The path to the page, relative to the content directory. Required. +: (`string`) The path to the page, relative to the `content` directory. Required. lang : (`string`) The language (site) to search for the page. Default is the current language. Optional. diff --git a/content/en/methods/page/RelRef.md b/content/en/methods/page/RelRef.md index 4c635e0e2..83ab08610 100644 --- a/content/en/methods/page/RelRef.md +++ b/content/en/methods/page/RelRef.md @@ -15,7 +15,7 @@ action: The map of option contains: path -: (`string`) The path to the page, relative to the content directory. Required. +: (`string`) The path to the page, relative to the `content` directory. Required. lang : (`string`) The language (site) to search for the page. Default is the current language. Optional. diff --git a/content/en/methods/page/Render.md b/content/en/methods/page/Render.md index 66aa6be7b..b5306822b 100644 --- a/content/en/methods/page/Render.md +++ b/content/en/methods/page/Render.md @@ -28,7 +28,7 @@ Although similar to the [`partial`] function, there are key differences. `Render` method|`partial` function| :--|:-- The `Page` object is automatically passed to the given template. You cannot pass additional context.| You must specify the context, allowing you to pass a combination of objects, slices, maps, and scalars. -The path to the template is determined by the [content type].|You must specify the path to the template, relative to the layouts/partials directory. +The path to the template is determined by the [content type].|You must specify the path to the template, relative to the `layouts/partials` directory. Consider this layout structure: diff --git a/content/en/methods/page/_common/definition-of-section.md b/content/en/methods/page/_common/definition-of-section.md index 79e22b10d..4a2e36ff3 100644 --- a/content/en/methods/page/_common/definition-of-section.md +++ b/content/en/methods/page/_common/definition-of-section.md @@ -2,4 +2,4 @@ _comment: Do not remove front matter. --- -A _section_ is a top-level content directory, or any content directory with an _index.md file. +A _section_ is a top-level content directory, or any content directory with an `_index.md` file. diff --git a/content/en/methods/resource/Name.md b/content/en/methods/resource/Name.md index 694b67baa..0c34ff2bf 100644 --- a/content/en/methods/resource/Name.md +++ b/content/en/methods/resource/Name.md @@ -15,7 +15,7 @@ The value returned by the `Name` method on a `Resource` object depends on the re ## Global resource -With a [global resource], the `Name` method returns the path to the resource, relative to the assets directory. +With a [global resource], the `Name` method returns the path to the resource, relative to the `assets` directory. ```text assets/ diff --git a/content/en/methods/resource/Title.md b/content/en/methods/resource/Title.md index c620c2448..58c61c4c5 100644 --- a/content/en/methods/resource/Title.md +++ b/content/en/methods/resource/Title.md @@ -15,7 +15,7 @@ The value returned by the `Title` method on a `Resource` object depends on the r ## Global resource -With a [global resource], the `Title` method returns the path to the resource, relative to the assets directory. +With a [global resource], the `Title` method returns the path to the resource, relative to the `assets` directory. ```text assets/ diff --git a/content/en/methods/shortcode/Ref.md b/content/en/methods/shortcode/Ref.md index 293c772d9..305e1e7d8 100644 --- a/content/en/methods/shortcode/Ref.md +++ b/content/en/methods/shortcode/Ref.md @@ -15,7 +15,7 @@ action: The map of option contains: path -: (`string`) The path to the page, relative to the content directory. Required. +: (`string`) The path to the page, relative to the `content` directory. Required. lang : (`string`) The language (site) to search for the page. Default is the current language. Optional. diff --git a/content/en/methods/shortcode/RelRef.md b/content/en/methods/shortcode/RelRef.md index 07f221a99..4e367312b 100644 --- a/content/en/methods/shortcode/RelRef.md +++ b/content/en/methods/shortcode/RelRef.md @@ -15,7 +15,7 @@ action: The map of option contains: path -: (`string`) The path to the page, relative to the content directory. Required. +: (`string`) The path to the page, relative to the `content` directory. Required. lang : (`string`) The language (site) to search for the page. Default is the current language. Optional. diff --git a/content/en/methods/site/Data.md b/content/en/methods/site/Data.md index 65cdadd01..f8e8e2e76 100644 --- a/content/en/methods/site/Data.md +++ b/content/en/methods/site/Data.md @@ -13,17 +13,17 @@ action: signatures: [SITE.Data] --- -Use the `Data` method on a `Site` object to access data within the data directory, or within any directory [mounted] to the data directory. Supported data formats include JSON, TOML, YAML, and XML. +Use the `Data` method on a `Site` object to access data within the `data` directory, or within any directory [mounted] to the `data` directory. Supported data formats include JSON, TOML, YAML, and XML. [mounted]: /hugo-modules/configuration/#module-configuration-mounts {{% note %}} -Although Hugo can unmarshal CSV files with the [`transform.Unmarshal`] function, do not place CSV files in the data directory. You cannot access data within CSV files using this method. +Although Hugo can unmarshal CSV files with the [`transform.Unmarshal`] function, do not place CSV files in the `data` directory. You cannot access data within CSV files using this method. [`transform.Unmarshal`]: /functions/transform/unmarshal/ {{% /note %}} -Consider this data directory: +Consider this `data` directory: ```text data/ diff --git a/content/en/methods/site/GetPage.md b/content/en/methods/site/GetPage.md index 2a972e2af..1466920b7 100644 --- a/content/en/methods/site/GetPage.md +++ b/content/en/methods/site/GetPage.md @@ -15,7 +15,7 @@ The `GetPage` method is also available on `Page` objects, allowing you to specif [details]: /methods/page/getpage/ -When using the `GetPage` method on a `Site` object, specify a path relative to the content directory. +When using the `GetPage` method on a `Site` object, specify a path relative to the `content` directory. If Hugo cannot resolve the path to a page, the method returns nil. diff --git a/content/en/myshowcase/index.md b/content/en/myshowcase/index.md index 08ea1e55f..4d706ccb8 100644 --- a/content/en/myshowcase/index.md +++ b/content/en/myshowcase/index.md @@ -20,7 +20,7 @@ byline: "[bep](https://github.com/bep), Hugo Lead" To complete this showcase: 1. Write the story about your site in this file. -2. Add a summary to the `bio.md` file in this folder. +2. Add a summary to the `bio.md` file in this directory. 3. Replace the `featured-template.png` with a screenshot of your site. You can rename it, but it must contain the word `featured`. 4. Create a new pull request in https://github.com/gohugoio/hugoDocs/pulls @@ -34,4 +34,3 @@ bio.md featured.png : A reasonably sized screenshot of your website. It can be named anything, but the name must start with "featured". The sample image is `1500x750` (2:1 aspect ratio). - diff --git a/content/en/render-hooks/images.md b/content/en/render-hooks/images.md index d3067c5a4..cf7322058 100755 --- a/content/en/render-hooks/images.md +++ b/content/en/render-hooks/images.md @@ -148,7 +148,7 @@ The embedded image render hook resolves internal Markdown destinations by lookin [page resource]: /getting-started/glossary/#page-resource [global resource]: /getting-started/glossary/#global-resource -You must place global resources in the assets directory. If you have placed your resources in the static directory, and you are unable or unwilling to move them, you must mount the static directory to the assets directory by including both of these entries in your site configuration: +You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your site configuration: {{< code-toggle file=hugo >}} [[module.mounts]] diff --git a/content/en/render-hooks/links.md b/content/en/render-hooks/links.md index 9505e989b..2ea3d9721 100755 --- a/content/en/render-hooks/links.md +++ b/content/en/render-hooks/links.md @@ -118,7 +118,7 @@ The embedded link render hook resolves internal Markdown destinations by looking [page resource]: /getting-started/glossary/#page-resource [global resource]: /getting-started/glossary/#global-resource -You must place global resources in the assets directory. If you have placed your resources in the static directory, and you are unable or unwilling to move them, you must mount the static directory to the assets directory by including both of these entries in your site configuration: +You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your site configuration: {{< code-toggle file=hugo >}} [[module.mounts]] diff --git a/content/en/shortcodes/figure.md b/content/en/shortcodes/figure.md index a71f808a4..3c6cd2e8b 100755 --- a/content/en/shortcodes/figure.md +++ b/content/en/shortcodes/figure.md @@ -108,7 +108,7 @@ The `figure` shortcode resolves internal Markdown destinations by looking for a [page resource]: /getting-started/glossary/#page-resource [global resource]: /getting-started/glossary/#global-resource -You must place global resources in the assets directory. If you have placed your resources in the static directory, and you are unable or unwilling to move them, you must mount the static directory to the assets directory by including both of these entries in your site configuration: +You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your site configuration: {{< code-toggle file=hugo >}} [[module.mounts]] diff --git a/content/en/showcase/1password-support/index.md b/content/en/showcase/1password-support/index.md index ed44053c8..c0a66ce45 100644 --- a/content/en/showcase/1password-support/index.md +++ b/content/en/showcase/1password-support/index.md @@ -21,7 +21,7 @@ Finding a tool that will make your customers, writers, designers, _and_ DevOps t **Hugo is FAST**. Our previous static site generator took nearly a minute to compile our (then much smaller) site. Developers might be used to this, but it wasn't cutting it for writers who wanted to see live previews of their work. Hugo did the same job in milliseconds, and to this day compiles 400 pages in five languages in the blink of an eye. -**Hugo is flexible**. Thanks to Hugo's content and layout system, we were able to preserve our existing file and folder structure and port our entire production site in a few days. We could then create new content types that weren't possible before, like these snazzy [showcases](https://support.1password.com/explore/extension/). +**Hugo is flexible**. Thanks to Hugo's content and layout system, we were able to preserve our existing file and directory structure and port our entire production site in a few days. We could then create new content types that weren't possible before, like these snazzy [showcases](https://support.1password.com/explore/extension/). **Hugo is great for writers**. Our documentation team was already comfortable with Markdown and Git and could start creating content for Hugo with zero downtime. Once we added shortcodes, our writers were able to dress up articles with features like [platform boxes](https://support.1password.com/get-the-apps/) with just a bit of new syntax. diff --git a/content/en/showcase/hartwell-insurance/index.md b/content/en/showcase/hartwell-insurance/index.md index ef0587e41..24b4e3a9f 100644 --- a/content/en/showcase/hartwell-insurance/index.md +++ b/content/en/showcase/hartwell-insurance/index.md @@ -62,7 +62,7 @@ The most encouraging result is how quick the site is around the world. Most Toma --- -This project was such a blast to develop, it’s a real pleasure to put new technologies to good use in production, and to see real performance and usability benefits from them. Even using classic web methods of serving folders with files is fun when you’ve been using dynamic systems for a while – there’s something really pure about it. +This project was such a blast to develop, it’s a real pleasure to put new technologies to good use in production, and to see real performance and usability benefits from them. Even using classic web methods of serving directories with files is fun when you’ve been using dynamic systems for a while – there’s something really pure about it. --- diff --git a/content/en/templates/404.md b/content/en/templates/404.md index cde195697..39df75c3d 100644 --- a/content/en/templates/404.md +++ b/content/en/templates/404.md @@ -11,7 +11,7 @@ menu: weight: 160 --- -To render a 404 error page in the root of your site, create a 404 template in the root of the layouts directory. For example: +To render a 404 error page in the root of your site, create a 404 template in the root of the `layouts` directory. For example: {{< code file=layouts/404.html >}} {{ define "main" }} diff --git a/content/en/templates/_index.md b/content/en/templates/_index.md index 23b2a3eaf..db26daf28 100644 --- a/content/en/templates/_index.md +++ b/content/en/templates/_index.md @@ -13,4 +13,4 @@ weight: 10 aliases: [/templates/overview/,/templates/content] --- -A template is an HTML file with [template actions](/getting-started/glossary/#template-action), located within the layouts directory of a project, theme, or module. Visit the topics below, in the order presented, to understand template selection and creation. +A template is an HTML file with [template actions](/getting-started/glossary/#template-action), located within the `layouts` directory of a project, theme, or module. Visit the topics below, in the order presented, to understand template selection and creation. diff --git a/content/en/templates/content-view.md b/content/en/templates/content-view.md index be4d7116a..7b995ece5 100644 --- a/content/en/templates/content-view.md +++ b/content/en/templates/content-view.md @@ -22,15 +22,15 @@ The following are common use cases for content views: To create a new view, create a template in each of your different content type directories with the view name. The following example contains an "li" view and a "summary" view for the `posts` and `project` content types. As you can see, these sit next to the [single template], `single.html`. You can even provide a specific view for a given type and continue to use the `_default/single.html` for the primary view. ```txt - ▾ layouts/ - ▾ posts/ - li.html - single.html - summary.html - ▾ project/ - li.html - single.html - summary.html +layouts/ +├── posts/ +│ ├── li.html +│ ├── single.html +│ └── summary.html +├── project/ +│ ├── li.html +│ └── single.html +└── summary.html ``` ## Which template will be rendered? diff --git a/content/en/templates/embedded.md b/content/en/templates/embedded.md index 2c386b5df..246381db2 100644 --- a/content/en/templates/embedded.md +++ b/content/en/templates/embedded.md @@ -15,7 +15,7 @@ aliases: [/templates/internal] ## Disqus {{% note %}} -To override Hugo's embedded Disqus template, copy the [source code] to a file with the same name in the layouts/partials directory, then call it from your templates using the [`partial`] function: +To override Hugo's embedded Disqus template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function: `{{ partial "disqus.html" . }}` @@ -58,7 +58,7 @@ You can also set the following in the front matter for a given piece of content: ## Google Analytics {{% note %}} -To override Hugo's embedded Google Analytics template, copy the [source code] to a file with the same name in the layouts/partials directory, then call it from your templates using the [`partial`] function: +To override Hugo's embedded Google Analytics template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function: `{{ partial "google_analytics.html" . }}` @@ -90,7 +90,7 @@ To use this value in your own template, access the configured ID with `{{ site.C ## Open Graph {{% note %}} -To override Hugo's embedded Open Graph template, copy the [source code] to a file with the same name in the layouts/partials directory, then call it from your templates using the [`partial`] function: +To override Hugo's embedded Open Graph template, copy the [source code] to a file with the same name in the `layouts/partials` directory, then call it from your templates using the [`partial`] function: `{{ partial "opengraph.html" . }}` @@ -149,7 +149,7 @@ If using YouTube this will produce a og:video tag like `