The pages directory
All pages of a Herbie website are stored in the directory
site/pages as plain text files.
These text files can be plain text, markdown, textile or HTML files.
In order for Herbie to recognize these files and convert them to HTML, they must contain a block of page properties in the header of the file.
Herbie currently supports the following file types:
When parsing the content, the formatter corresponding to the file extension is used. Thus, the content of a file with the extension .md is converted by the Markdown parser. And a file with the extension .textile by a Textile parser.
Creating a page
To create a new page, add a new file with one of the allowed extensions in the
You must respect the following rules:
- only lowercase letters, numbers, underscores and hyphens
- no umlauts, special or control characters
- no spaces
How you name the file will affect the web address and how the page is viewed in the browser. If you follow the above rules, you will get nicely readable and working links to the subpages of the website.
As the only file in the
site/pages directory, Herbie expects an index file with one of the above extensions.
This file takes over the function of the homepage or start page and is displayed when http://www.example.com is called in the browser.
If the index file is missing, a 404 error page is displayed.
Named text files
The easiest way to add pages is to add a text file with an appropriate name in the pages directory. For a site with a home page, an about page, and a contact page, the page directory and their corresponding URLs would look like this:
site/pages ├── about.md # https://example.com/about ├── contact.md # https://example.com/contact └── index.md # https://example.com
Named folders with index files
You can do it this way, and there is nothing wrong with it at all. However, often you want to add more pages or group existing pages into a topic. For example, if a team page, a vision page, and a route page are added to the above website, the page index might look like this:
site/pages ├── about │ ├── index.md # https://example.com/about │ ├── team.md # https://example.com/about/team │ └── vision.md # https://example.com/about/vision ├── contact │ ├── index.md # https://example.com/contact │ └── route.md # https://example.com/contact/route └── index.md # https://example.com
Which way is better depends largely on the type of website. For small websites, named text files without further sub folders are enough. For large websites, there is no way around additional sub folders and text files.
Visibility and sorting
By prefixing files with a number followed by a hyphen, you can control sorting and visibility in menus. It looks like this, for example:
site/pages ├── 1-index.md # visible and sorted ├── 2-about-us.md # visible and sorted ├── 3-contact.md # visible and sorted ├── imprint.md # not visible └── sitemap.md # not visible
The pages index, about-us and contact are visible in menus and sorting is defined. The pages sitemap and imprint are not visible in menus and sorting is therefore not relevant.
Note: For folders, the preceding number only affects the sorting, but not the visibility.
The visibility of folders is controlled by the index file in the folders.
Disable page or folder
Sometimes you want to disable a page or a whole folder. This can be done by prefixing the name of the page or folder with an underscore. Such pages and folders are not taken into account when scanning the file system.
site/pages ├── _about # The folder incl. subpages is disabled │ ├── index.md │ ├── team.md │ └── vision.md ├── contact │ ├── _route.md # The page is disabled │ └── index.md └── index.md
This is helpful, for example, when pages should be temporarily disabled.