Page bundles are a way to group page resources. I refer to page bundles documentation at https://gohugo.io.

This post is a page bundle. A page bundle is any directory within the content/ directory that contains an index.md page.

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

---

Content Sections

Hugo Content Management / Sections

• A Section is a collection of pages that gets defined based on the organization structure under the content/ directory.

• All first-level directories under content/ form their own sections (root sections).

• To define a section at a deeper level you need to create a branch bundle - a directory with an _index.md file. hugo new posts/my-post/_index.md.

• Sections can be nested as deeply as desired but to make the section fully navigational, at least the lower-most section needs a content file, i.e. a _index.md file.

• A _index.md file has a special role in Hugo, allowing front matter and content to be added to the list templates.

---

Some of my projects are quite long to have on a single page. I would like to have a project that can reference other markdown files within the same project’s directory.

• A project created as a single page or a page bundle (with an index.md) file will appear in the list of projects using {{ range (where .Site.RegularPages "Type" "in" "projects")}} or .Paginator.Pages. This lists each page in the entire site that are in the “projects” content section. (.Pages also works).

• A project page bundle created with an _index.md file will not appear when .Paginator.Pages is used for the projects list template.

• .RegularPagesRecursive should list all regular pages under a list page, including regular pages in nested sections / list pages.)

For example I first created a test project called testlinks using hugo new projects/testlinks/_index.md and then created two markdown pages “testpage1.md” and “testpage2.md” within the “testlinks” project directory. * hugo new projects/testlinks/testpage1.md * hugo new projects/testlinks/testpage2.md

The “testlinks” project will not show up in the list of projects but the two markdown pages created within the bundle will be picked up by .Site.RegularPages.

• link to testlinks project A project created with an _index.md file which does not show up in the list of projects

• From within testlinks project I can link to the two markdown pages using just the name of the markdown file name (without the “.md” extension.) as follows:

  • testpage1
  • test1page

• I can also link to the “testlinks” project _index.md page from another (single page) project using ../testlinks and to one of the markdown files within it using ../testlinks/testpage1.

• Using .RegularPagesRecursive in the projects/list.html template will list “testpage1” and “testpage2” file but not testlinks itself while {{ range .Paginator.Pages }} will only list the names of the projects created as single page posts or using an .index.md file but not an _index.md project such as testlinks. It uses an internal pagination.html template.

I can link to another project such as simulation project (created as a page bundle with an index.md file) but not the “page2.md” file created within the simulations project directory.

So I can link to markdown posts within a project page bundle if the page bundle has a _index.md file. But I cannot link to markdown posts within a project page bundle if it has an index.md file. On the other hand the page bundle created with a index.md file will show up in the list of projects (using .Paginator.Pages) but the page bundle created with a _index.md file will not show up in this list page. The markdown files within the project folder will appear when using .Site.RegularPages in projects.