index.md (9537B)
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 date: 2017-02-01
6 publishdate: 2017-02-01
7 lastmod: 2017-02-01
8 categories: [content management,fundamentals]
9 keywords: [sections,content,organization,bundle,resources]
10 menu:
11 docs:
12 parent: "content-management"
13 weight: 10
14 weight: 10 #rem
15 draft: false
16 aliases: [/content/sections/]
17 toc: true
18 ---
19
20 ## Page Bundles
21
22 Hugo `0.32` announced page-relative images and other resources packaged into `Page Bundles`.
23
24 These terms are connected, and you also need to read about [Page Resources]({{< relref "/content-management/page-resources" >}}) and [Image Processing]({{< relref "/content-management/image-processing" >}}) to get the full picture.
25
26 {{< imgproc 1-featured Resize "300x" >}}
27 The illustration shows three bundles. Note that the home page bundle cannot contain other content pages, although other files (images etc.) are allowed.
28 {{< /imgproc >}}
29
30
31 {{% note %}}
32 The bundle documentation is a **work in progress**. We will publish more comprehensive docs about this soon.
33 {{% /note %}}
34
35
36 ## Organization of Content Source
37
38
39 In Hugo, your content should be organized in a manner that reflects the rendered website.
40
41 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][].
42
43 Without any additional configuration, the following will automatically work:
44
45 ```
46 .
47 └── content
48 └── about
49 | └── index.md // <- https://example.com/about/
50 ├── posts
51 | ├── firstpost.md // <- https://example.com/posts/firstpost/
52 | ├── happy
53 | | └── ness.md // <- https://example.com/posts/happy/ness/
54 | └── secondpost.md // <- https://example.com/posts/secondpost/
55 └── quote
56 ├── first.md // <- https://example.com/quote/first/
57 └── second.md // <- https://example.com/quote/second/
58 ```
59
60 ## Path Breakdown in Hugo
61
62
63 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.com"` in your [site's configuration file][config].
64
65 ### Index Pages: `_index.md`
66
67 `_index.md` has a special role in Hugo. It allows you to add front matter and content to your [list templates][lists]. These templates include those for [section templates][], [taxonomy templates][], [taxonomy terms templates][], and your [homepage template][].
68
69 {{% note %}}
70 **Tip:** You can get a reference to the content and metadata in `_index.md` using the [`.Site.GetPage` function](/functions/getpage/).
71 {{% /note %}}
72
73 You can create one `_index.md` for your homepage and one in each of your content sections, taxonomies, and taxonomy 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
76 ```
77 . url
78 . ⊢--^-⊣
79 . path slug
80 . ⊢--^-⊣⊢---^---⊣
81 . filepath
82 . ⊢------^------⊣
83 content/posts/_index.md
84 ```
85
86 At build, this will output to the following destination with the associated values:
87
88 ```
89
90 url ("/posts/")
91 ⊢-^-⊣
92 baseurl section ("posts")
93 ⊢--------^---------⊣⊢-^-⊣
94 permalink
95 ⊢----------^-------------⊣
96 https://example.com/posts/index.html
97 ```
98
99 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`).
100
101
102 ### Single Pages in Sections
103
104 Single content files in each of your sections will be rendered as [single page templates][singles]. Here is an example of a single `post` within `posts`:
105
106
107 ```
108 path ("posts/my-first-hugo-post.md")
109 . ⊢-----------^------------⊣
110 . section slug
111 . ⊢-^-⊣⊢--------^----------⊣
112 content/posts/my-first-hugo-post.md
113 ```
114
115 When Hugo builds your site, the content will be output to the following destination:
116
117 ```
118
119 url ("/posts/my-first-hugo-post/")
120 ⊢------------^----------⊣
121 baseurl section slug
122 ⊢--------^--------⊣⊢-^--⊣⊢-------^---------⊣
123 permalink
124 ⊢--------------------^---------------------⊣
125 https://example.com/posts/my-first-hugo-post/index.html
126 ```
127
128
129 ## Paths Explained
130
131 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.
132
133 ### `section`
134
135 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.
136
137 ### `slug`
138
139 A content's `slug` is either `name.extension` or `name/`. The value for `slug` is determined by
140
141 * the name of the content file (e.g., `lollapalooza.md`) OR
142 * front matter overrides
143
144 ### `path`
145
146 A content's `path` is determined by the section's path to the file. The file `path`
147
148 * is based on the path to the content's location AND
149 * does not include the slug
150
151 ### `url`
152
153 The `url` is the relative URL for the piece of content. The `url`
154
155 * is based on the content item's location within the directory structure OR
156 * is defined in front matter, in which case it *overrides all the above*
157
158 ## Override Destination Paths via Front Matter
159
160 Hugo assumes that your content is organized with a purpose. The same structure that you use to organize your source content is used to organize the rendered site. As displayed above, the organization of the source content will be mirrored at the destination.
161
162 There are times when you may need more fine-grained control over the content organization. In such cases, the front matter field can be used to determine the destination of a specific piece of content.
163
164 The following items are defined in a specific order for a reason: items explained lower down in the list override higher items. Note that not all items can be defined in front matter.
165
166 ### `filename`
167
168 `filename` is not a front matter field. It is the actual file name, minus the extension. This will be the name of the file in the destination (e.g., `content/posts/my-post.md` becomes `example.com/posts/my-post/`).
169
170 ### `slug`
171
172 When defined in the front matter, the `slug` can take the place of the filename in the destination.
173
174 {{< code file="content/posts/old-post.md" >}}
175 ---
176 title: A new post with the filename old-post.md
177 slug: "new-post"
178 ---
179 {{< /code >}}
180
181 This will render to the following destination according to Hugo's default behavior:
182
183 ```
184 example.com/posts/new-post/
185 ```
186
187 ### `section`
188
189 `section` is determined by a content item's location on disk and *cannot* be specified in the front matter. See [sections] for more information.
190
191 ### `type`
192
193 A content item's `type` is also determined by its location on disk but, unlike `section`, it *can* be specified in the front matter. See [types]. This can come in especially handy when you want a piece of content to render using a different layout. In the following example, you can create a layout at `layouts/new/mylayout.html` that Hugo will use to render this piece of content, even in the midst of many other posts.
194
195 {{< code file="content/posts/my-post.md" >}}
196 ---
197 title: My Post
198 type: new
199 layout: mylayout
200 ---
201 {{< /code >}}
202 <!-- See https://discourse.gohugo.io/t/path-not-works/6387 -->
203 <!-- ### `path`-->
204
205 <!--`path` can be provided in the front matter. This will replace the actual path to the file on disk. Destination will create the destination with the same path, including the section. -->
206
207 ### `url`
208
209 A complete URL can be provided. This will override all the above as it pertains to the end destination. This must be the path from the baseURL (starting with a `/`). `url` will be used exactly as it is defined in the front matter, and will ignore the `--uglyURLs` setting in your site configuration:
210
211 {{< code file="content/posts/old-url.md" >}}
212 ---
213 title: Old URL
214 url: /blog/new-url/
215 ---
216 {{< /code >}}
217
218 Assuming your `baseURL` is [configured][config] to `https://example.com`, the addition of `url` to the front matter will make `old-url.md` render to the following destination:
219
220 ```
221 https://example.com/blog/new-url/
222 ```
223
224 You can see more information on how to control output paths in [URL Management][urls].
225
226 [config]: /getting-started/configuration/
227 [formats]: /content-management/formats/
228 [front matter]: /content-management/front-matter/
229 [getpage]: /functions/getpage/
230 [homepage template]: /templates/homepage/
231 [homepage]: /templates/homepage/
232 [lists]: /templates/lists/
233 [pretty]: /content-management/urls/#pretty-urls
234 [section templates]: /templates/section-templates/
235 [sections]: /content-management/sections/
236 [singles]: /templates/single-page-templates/
237 [taxonomy templates]: /templates/taxonomy-templates/
238 [taxonomy terms templates]: /templates/taxonomy-templates/
239 [types]: /content-management/types/
240 [urls]: /content-management/urls/