It is easy to link to images within a folder using page bundles. I wanted to be able to have several markdown posts within a project and then to be able to link to them from the project home page.
Page bundles are a way to group page resources as outlined in the page bundles documentation at https://gohugo.io.
A page bundle can be a leaf bundle or a branch bundle.
- A leaf bundle is a collection of content and attachments for single pages such as this post.
This post is a leaf bundle. The index file name is index.md. To create a page bundle you use the hugo new <section>/<post-name>/index.md. For example to create a new page bundle post called “my-page-bundle-post” use the command hugo new post/my-page-bundle-post/index.md instead of hugo new post/my-page-bundle-post.md.
- A branch bundle is a collection of attachments for section pages such as the home page section, taxonomy terms etc. The various
The index file name for a branch bundle post is _index.md. Only non-page resources such as images and pdfs are allowed for branch bundles while page resources are also allowed for leaf bundles.
This post is a page bundle. A page bundle is any directory within the content/ directory that contains an index.md page.
Initially I was trying to link to markdown pages within a project folder. I found that if I created an index.md file for the page bundle then I could not easily link to pages within the page bundle folder, although I could easily link to posts in other folders.
Linking using markdown relative links.
Here are some links to other projects in the content/projects section of the website. These projects are page bundles and have an index.md file. They can be linked to by using markdown links using relative references. ../ will go one level up the tree, ../../ will go two levels up the tree.
- Link to Open Data project project using
../open-data.
Linking using rel and relref shortcodes.
Here are some links to the same projects using shortcodes to look up the pages by their relative paths.
The links take the form of [link name] with the relative path specified inside quotes inside {{ < relref "../project-name" > }}
Using a _index.md file instead does allow you to link to markdown posts within the bundle, however the project bundle would not appear in the list of projects when I used .Paginator.Pages. It will appear when using just .Pages, therefore I am using .Pages to list projects. I am still using .Paginator.Pages to list blog posts.
An alternative way is to create another project page bundle with the markdown pages. Then link to these from the original project post using the relative links.
Ordering pages within the page bundle.
Ordering the content within a project can be achieved using the weight parameter in the front matter section. A lower weight will list the page near the top of the pages.