| 1 |
--- |
| 2 |
title: Content organization |
| 3 |
linkTitle: Organization |
| 4 |
description: Hugo assumes that the same structure that works to organize your source content is used to organize the rendered site. |
| 5 |
categories: [] |
| 6 |
keywords: [] |
| 7 |
aliases: [/content/sections/] |
| 8 |
--- |
| 9 |
|
| 10 |
## Page bundles |
| 11 |
|
| 12 |
Hugo supports page-relative images and other resources packaged into `Page Bundles`. |
| 13 |
|
| 14 |
These terms are connected, and you also need to read about [Page Resources](/content-management/page-resources) and [Image Processing](/content-management/image-processing) to get the full picture. |
| 15 |
|
| 16 |
```text |
| 17 |
content/ |
| 18 |
├── blog/ |
| 19 |
│ ├── hugo-is-cool/ |
| 20 |
│ │ ├── images/ |
| 21 |
│ │ │ ├── funnier-cat.jpg |
| 22 |
│ │ │ └── funny-cat.jpg |
| 23 |
│ │ ├── cats-info.md |
| 24 |
│ │ └── index.md |
| 25 |
│ ├── posts/ |
| 26 |
│ │ ├── post1.md |
| 27 |
│ │ └── post2.md |
| 28 |
│ ├── 1-landscape.jpg |
| 29 |
│ ├── 2-sunset.jpg |
| 30 |
│ ├── _index.md |
| 31 |
│ ├── content-1.md |
| 32 |
│ └── content-2.md |
| 33 |
├── 1-logo.png |
| 34 |
└── _index.md |
| 35 |
``` |
| 36 |
|
| 37 |
The file tree above shows three bundles. Note that the home page bundle cannot contain other content pages, although other files (images etc.) are allowed. |
| 38 |
|
| 39 |
## Organization of content source |
| 40 |
|
| 41 |
In Hugo, your content should be organized in a manner that reflects the rendered website. |
| 42 |
|
| 43 |
While Hugo supports content nested at any level, the top levels (i.e. `content/<DIRECTORIES>`) are special in Hugo and are considered the content type used to determine layouts etc. To read more about sections, including how to nest them, see [sections]. |
| 44 |
|
| 45 |
Without any additional configuration, the following will automatically work: |
| 46 |
|
| 47 |
```txt |
| 48 |
. |
| 49 |
└── content |
| 50 |
└── about |
| 51 |
| └── index.md // <- https://example.org/about/ |
| 52 |
├── posts |
| 53 |
| ├── firstpost.md // <- https://example.org/posts/firstpost/ |
| 54 |
| ├── happy |
| 55 |
| | └── ness.md // <- https://example.org/posts/happy/ness/ |
| 56 |
| └── secondpost.md // <- https://example.org/posts/secondpost/ |
| 57 |
└── quote |
| 58 |
├── first.md // <- https://example.org/quote/first/ |
| 59 |
└── second.md // <- https://example.org/quote/second/ |
| 60 |
``` |
| 61 |
|
| 62 |
## Path breakdown in Hugo |
| 63 |
|
| 64 |
The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseURL = "https://example.org/"` in your [project configuration][config]. |
| 65 |
|
| 66 |
### Index pages: `_index.md` |
| 67 |
|
| 68 |
`_index.md` has a special role in Hugo. It allows you to add front matter and content to `home`, `section`, `taxonomy`, and `term` pages. |
| 69 |
|
| 70 |
> [!note] |
| 71 |
> Access the content and metadata within an `_index.md` file by invoking the `GetPage` method on a `Site` or `Page` object. |
| 72 |
|
| 73 |
You can create one `_index.md` for your home page and one in each of your content sections, taxonomies, and terms. The following shows typical placement of an `_index.md` that would contain content and front matter for a `posts` section list page on a Hugo website: |
| 74 |
|
| 75 |
```txt |
| 76 |
. url |
| 77 |
. ⊢--^-⊣ |
| 78 |
. path slug |
| 79 |
. ⊢--^-⊣⊢---^---⊣ |
| 80 |
. file path |
| 81 |
. ⊢------^------⊣ |
| 82 |
content/posts/_index.md |
| 83 |
``` |
| 84 |
|
| 85 |
At build, this will output to the following destination with the associated values: |
| 86 |
|
| 87 |
```txt |
| 88 |
|
| 89 |
url ("/posts/") |
| 90 |
⊢-^-⊣ |
| 91 |
baseurl section ("posts") |
| 92 |
⊢--------^---------⊣⊢-^-⊣ |
| 93 |
permalink |
| 94 |
⊢----------^-------------⊣ |
| 95 |
https://example.org/posts/index.html |
| 96 |
``` |
| 97 |
|
| 98 |
The [sections] can be nested as deeply as you want. The important thing to understand is that to make the section tree fully navigational, at least the lower-most section must include a content file. (i.e. `_index.md`). |
| 99 |
|
| 100 |
### Single pages in sections |
| 101 |
|
| 102 |
Single content files in each of your sections will be rendered by a [page template]. Here is an example of a single `post` within `posts`: |
| 103 |
|
| 104 |
```txt |
| 105 |
path ("posts/my-first-hugo-post.md") |
| 106 |
. ⊢-----------^------------⊣ |
| 107 |
. section slug |
| 108 |
. ⊢-^-⊣⊢--------^----------⊣ |
| 109 |
content/posts/my-first-hugo-post.md |
| 110 |
``` |
| 111 |
|
| 112 |
When Hugo builds your site, the content will be output to the following destination: |
| 113 |
|
| 114 |
```txt |
| 115 |
|
| 116 |
url ("/posts/my-first-hugo-post/") |
| 117 |
⊢------------^----------⊣ |
| 118 |
baseurl section slug |
| 119 |
⊢--------^--------⊣⊢-^--⊣⊢-------^---------⊣ |
| 120 |
permalink |
| 121 |
⊢--------------------^---------------------⊣ |
| 122 |
https://example.org/posts/my-first-hugo-post/index.html |
| 123 |
``` |
| 124 |
|
| 125 |
## Paths explained |
| 126 |
|
| 127 |
The following concepts provide more insight into the relationship between your project's organization and the default Hugo behavior when building output for the website. |
| 128 |
|
| 129 |
### `section` |
| 130 |
|
| 131 |
A default content type is determined by the section in which a content item is stored. `section` is determined by the location within the project's `content` directory. `section` cannot be specified or overridden in front matter. |
| 132 |
|
| 133 |
### `slug` |
| 134 |
|
| 135 |
The `slug` is the last segment of the URL path, defined by the file name and optionally overridden by a `slug` value in front matter. See [URL Management](/content-management/urls/#slug) for details. |
| 136 |
|
| 137 |
### `path` |
| 138 |
|
| 139 |
A content's `path` is determined by the section's path to the file. The file `path`: |
| 140 |
|
| 141 |
- Is based on the path to the content's location AND |
| 142 |
- Does not include the slug |
| 143 |
|
| 144 |
### `url` |
| 145 |
|
| 146 |
The `url` is the entire URL path, defined by the file path and optionally overridden by a `url` value in front matter. See [URL Management](/content-management/urls/#slug) for details. |
| 147 |
|
| 148 |
[config]: /configuration/ |
| 149 |
[pretty]: /content-management/urls/#appearance |
| 150 |
[sections]: /content-management/sections/ |
| 151 |
[page template]: /templates/types/#page |