--- title: Organize Files weight: 1 prev: /docs/guide --- ## Directory Structure By default, Hugo searches for Markdown files in the `content` directory, and the structure of the directory determines the final output structure of your website. Take this site as an example: {{< filetree/container >}} {{< filetree/folder name="content" >}} {{< filetree/file name="_index.md" >}} {{< filetree/folder name="docs" state="open" >}} {{< filetree/file name="_index.md" >}} {{< filetree/file name="getting-started.md" >}} {{< filetree/folder name="guide" state="open" >}} {{< filetree/file name="_index.md" >}} {{< filetree/file name="organize-files.md" >}} {{< /filetree/folder >}} {{< /filetree/folder >}} {{< filetree/folder name="blog" state="open" >}} {{< filetree/file name="_index.md" >}} {{< filetree/file name="post-1.md" >}} {{< /filetree/folder >}} {{< /filetree/folder >}} {{< /filetree/container >}} Each of the `_index.md` files is the index page for the corresponding section. The other Markdown files are regular pages. ``` content ├── _index.md // <- / ├── docs │ ├── _index.md // <- /docs/ │ ├── getting-started.md // <- /docs/getting-started/ │ └── guide │ ├── _index.md // <- /docs/guide/ │ └── organize-files.md // <- /docs/guide/organize-files/ └── blog ├── _index.md // <- /blog/ └── post-1.md // <- /blog/post-1/ ``` ## Layouts Hextra offers three layouts for different content types: | Layout | Directory | Features | | :-------- | :-------------------- | :--------------------------------------------------------------- | | `docs` | `content/docs/` | Ideal for structured documentation, same as this section. | | `blog` | `content/blog/` | For blog postings, with both listing and detailed article views. | | `default` | All other directories | Single-page article view without sidebar. | To customize a section to mirror the behavior of a built-in layout, specify the desired type in the front matter of the section's `_index.md`. ```yaml {filename="content/my-docs/_index.md"} --- title: My Docs cascade: type: docs --- ``` The above example configuration ensures that the content files inside `content/my-docs/` will be treated as documentation (`docs` type) by default. ## Sidebar Navigation The sidebar navigation is generated automatically based on the content organization alphabetically. To manually configure the sidebar order, we can use the `weight` parameter in the front matter of the Markdown files. ```yaml {filename="content/docs/guide/_index.md"} --- title: Guide weight: 2 --- ``` {{< callout emoji="ℹ️">}} It is recommended to keep the sidebar not too deep. If you have a lot of content, consider **splitting them into multiple sections**. {{< /callout >}} ## Breadcrumb Navigation Breadcrumbs are auto-generated based on the directory structure of `/content`. For example, consider the file structure [demonstrated above](#directory-structure). Given that structure, the breadcrumbs atop the page at `/docs/guide/organize-files/` would appear automatically as follows: ``` Documentation > Guide > Organize Files ``` ### Customizing Breadcrumb Link Titles By default, each breadcrumb link is generated based on that page's `title` parameter. You can customize this by specifying a `linkTitle`. For example, if instead of `Organize Files` we wanted the breadcrumb to be `Foo Bar`: ```yaml {filename="content/docs/guide/organize-files.md"} --- linkTitle: Foo Bar title: Organize Files --- ``` This would now generate the following breadcrumbs: ``` Documentation > Guide > Foo Bar ``` ### Hiding Breadcrumbs You can hide breadcrumbs completely from a page by specifying `breadcrumbs: false` in its front matter: ```yaml {filename="content/docs/guide/organize-files.md"} --- breadcrumbs: false title: Organize Files --- ``` ## Configure Content Directory By default, the root `content/` directory is used by Hugo to build the site. If you need to use a different directory for content, for example `docs/`, this can be done by setting the [`contentDir`](https://gohugo.io/getting-started/configuration/#contentdir) parameter in the site configuration `hugo.yaml`. ## Add Images To add images, the easiest way is to put the image files in the same directory as the Markdown file. For example, add an image file `image.png` alongside the `my-page.md` file: {{< filetree/container >}} {{< filetree/folder name="content" >}} {{< filetree/folder name="docs" >}} {{< filetree/file name="my-page.md" >}} {{< filetree/file name="image.png" >}} {{< /filetree/folder >}} {{< /filetree/folder >}} {{< /filetree/container >}} Then, we can use the following Markdown syntax to add the image to the content: ```markdown {filename="content/docs/my-page.md"} ![](image.png) ``` We can also utilize the [page bundles][page-bundles] feature of Hugo to organize the image files together with the Markdown file. To achieve that, turn the `my-page.md` file into a directory `my-page` and put the content into a file named `index.md`, and put the image files inside the `my-page` directory: {{< filetree/container >}} {{< filetree/folder name="content" >}} {{< filetree/folder name="docs" >}} {{< filetree/folder name="my-page" >}} {{< filetree/file name="index.md" >}} {{< filetree/file name="image.png" >}} {{< /filetree/folder >}} {{< /filetree/folder >}} {{< /filetree/folder >}} {{< /filetree/container >}} ```markdown {filename="content/docs/my-page/index.md"} ![](image.png) ``` Alternatively, we can also put the image files in the `static` directory, which will make the images available for all pages: {{< filetree/container >}} {{< filetree/folder name="static" >}} {{< filetree/folder name="images" >}} {{< filetree/file name="image.png" >}} {{< /filetree/folder >}} {{< /filetree/folder >}} {{< filetree/folder name="content" >}} {{< filetree/folder name="docs" >}} {{< filetree/file name="my-page.md" >}} {{< /filetree/folder >}} {{< /filetree/folder >}} {{< /filetree/container >}} Note that the image path begins with a slash `/` and is relative to the static directory: ```markdown {filename="content/docs/my-page.md"} ![](/images/image.png) ``` [page-bundles]: https://gohugo.io/content-management/page-bundles/#leaf-bundles