Fragments are the base building block of your website.
Each page is made up of one or multiple fragments.
These can be a navigation fragment, a content fragment and more.
In Hugo, the simplest way to create a page is to create a directory containing an index.md file.
If you need to create a new section for your website, then instead of an index.md file, simply create _index.md.
Section pages in Hugo are mostly called list and other pages are called single.
After creating your page, you need to create fragments to populate that page.
Each fragment is controlled by a content file.
This file is located next to index.md of the page if the page is single or in the _index directory if the page is a section one or homepage.
- content/my-page/index.md: defines the page and a few attributes such as page title
- content/my-page/my-fragment.md: content file for a fragment specified as attribute fragment = "content"
fragment = "content"
That fragment file should contain at least the following:
fragment = "[The fragment you want to use]"
weight = 10
For single pages, the directory content would look something like the following:
| ├── index.md
| ├── nav.md
| ├── hero
| | ├── index.md
For list pages, it’s just a bit different:
| ├── my-section
| | ├── _index.md
| | ├── _index
| | | ├── index.md
| | ├── my-page
| | | ├── index.md
Global fragments such as nav and footer and copyright can be located in the content/_global directory.
Fragments located in this directory would appear in every page unless there’s another fragment with the same name closer to the page.
For fragments of a website, that need to show up on every page, we have global fragments.
Global fragments are located in a special content directory content/_global/.
All fragments within this directory are rendered on all pages by default.
To prevent the page being rendered as a separate page on your website, we define the whole directory as a headless bundle within the index.md file.
To overwrite a global fragment create a per page fragment with the same filename.
This would overwrite the global one.
Aside from the content/_global/ directory, you can create _global/ directory in any section’s directory (content/[section]/_global/).
Each section can have global fragments and if there are multiple fragments with the same name, the fragment closest to the page would override the others.
There are several pre-bundled fragments already available in Syna. You can see the full list and their documentation in the fragments section.
These fragments make use of some global variables along with their own variables which are mentioned in the fragment’s page.
You can add your own custom fragment by creating a new layout file within your website’s layouts/partials/fragments/ directory.
If this path doesn’t exist yet, you can create it beforehand.
For image bundling or subitems in fragments such as member or items a subdirectory should be used.
fragment = "member"
The attributes and content of this file are passed to the specified fragment (fragment = "member").
Using the weight attribute you can specify the order.
As mentioned, fragments are controlled by content files.
There is one exception and that is menus.
Hugo does not allow menus to be defined in content files.
In order to customize menu options for a fragment you need to configure them within your website’s config.toml file.
As of right now there are three fragments using menus:
Whenever Hugo allows for resource menus or when we figure out a way to have menu features with frontmatter arrays this would change and menus would be configurable with resource variables like everything else. The change would be breaking. So when updating the theme please read the CHANGELOG and check for breaking changes.
Furthermore we use two keywords, that can’t be used to create pages.
Both ìndex and global have a special meaning within the Syna fragment and using them separately might lead to issues.