Organize Files

Organize Files

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:

    • _index.md
      • _index.md
      • getting-started.md
        • _index.md
        • organize-files.md
      • _index.md
      • post-1.md
  • 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:

    LayoutDirectoryFeatures
    docscontent/docs/Ideal for structured documentation, same as this section.
    blogcontent/blog/For blog postings, with both listing and detailed article views.
    defaultAll other directoriesSingle-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.

    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.

    content/docs/guide/_index.md
    ---
    title: Guide
    weight: 2
    ---
    ℹ️
    It is recommended to keep the sidebar not too deep. If you have a lot of content, consider splitting them into multiple sections.

    Breadcrumb Navigation

    Breadcrumbs are auto-generated based on the directory structure of /content.

    For example, consider the file structure demonstrated above. 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:

    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 specfying breadcrumbs: false in its front matter:

    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 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:

      • my-page.md
      • image.png
  • Then, we can use the following Markdown syntax to add the image to the content:

    content/docs/my-page.md
    ![](image.png)

    We can also utilize the 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:

        • index.md
        • image.png
  • 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:

      • image.png
      • my-page.md
  • Note that the image path begins with a slash / and is relative to the static directory:

    content/docs/my-page.md
    ![](/images/image.png)
    Last updated on