The folder structure lays the foundation for the website structure. Perplex relies mostly on Hugo’s page bundle features.
It may take a little while to get your head around Hugo’s content folder structure. Its helping me to keep its general concept in mind: Hugo processes our folder structure and all the files therein following the shortest logic path. Therefore, all overhead is avoided but small details can matter.
The content of the root itself / and the folders doc, news, blog and article may contain Markdown files and their resources. The theme provides different layout templates for them. Hugo applies the matching templates automatically to every content file inside these directories and their subdirectories.
- The root /
- may contain top level pages
- is for the documentation and can handle three folder levels deep filled with Markdown files and their resources.
- is for very short postings like announcements, which are listed in a continuous stream on the top level news page.
- is for short postings, which are accessible through the top level blog list page.
- is for longer postings or essays, which are listed as cards on a top level page.
You may have already created the new demo file
blog/first.md while following the example in the section first content. This is the simplest way to generate a new posting without any additional resources.
When we include resources like images into a page, we like to retrieve them easily. When we need some files only on a specific page, we can create a leaf bundle like this:
hugo new blog/my-second-post/index.md
index.md is rendered again as a single page, but now we can move page-specific resources in the folder of the leaf branch and access them directly via their filename.
When the number of blog entries rises, we need some structure. This is achieved with taxonomies, and Hugo’s defaults are the usual categories and tags. We can use them immediately, the front matter already includes the empty parameter keys:
When we add our taxonomies as a comma separated list inside the empty
, Hugo will generate additional list pages for every taxonomy we introduced.
A larger documentation site needs a clear hierarchy, a sidebar navigation and a search engine (TODO!), to find pages as quickly as possible. And to read the documentation like a book, we need references to the next and the previous pages and also to . All these navigational elements are build from parameters in the front matter. When we create a new documentation page with
hugo new doc/demo/my-first-doc-page.md
we start with a front matter, that contains a few more entries than a blog post. The first 5 lines, that we already have seen, are left out:
The new parameter weight is of general meaning for the order of all pages, the others are menu entries and are lined up under the `` section and are specifically creating the structure of the doc menu
- lets a page fall deeper in the hierarchy, the higher it gets. Right now our new doc page has an entry at the bottom of the sidebar navigation, take a look.
- is the title of the menu entry. If the page title is very long, we can provide a short version to avoid a messy menu.
- is an internal name, that lets other pages refer to this one as their
- If this parameter contains the identifier of another page, the current page is a level beyond its parent in the menu. If there is no parent, the page gets a top level menu entry.
- is used very specific by Perplex: It contains the identifier of a Material Icon from Google. To change it, please visit their website. You can pick any icon there. Select it and copy the identifier from the icon font embedding section (It’s usually the icon name written in lower letters and with underscores
_instead of spaces).
Besides single pages we usually need list pages. They can show an overview of the content of sections and provide some kind of introduction.
Because our new page is a demonstration, we like to file it in a special section. We create this demo section as a branch bundle with the following command:
hugo new doc/demo/_index.md
The small difference between a leaf bundle for a single page and a branch bundle is the leading underscore for the Markdown master file. It’s only
_index.md. But they have a very different purpose. A folder with a leaf bundle collects material for one page. A branch bundle collects as many pages and may include as many other bundles as we need — there is no technical limit to the depth of folder hierarchy. A branch bundle can act like a chapter, section or subsection.
_index.md should contain general content about this section. The page for a branch bundle usually also presents a list of selected content from every page in the branch.
To reflect this relationship in the menu, we need to set
parent = "demo" in
my-first-doc-page and Hugo rearranges the page structure and the menu alike.