Debian Codegraph @

docs/content/en/content-management/organization/index.md

raw
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