Support content partials (aka modular pages) (👍13)

[fvsch]

This feature suggestion is partly related to #250.

Rationale

Long web pages are often split in a few sections.
For a marketing page, this could be: hero content -> section 1 -> section 2 -> section 3…
For a documentation page, it could be collapsible sections, or we want to render a table of contents and anchors on each section's title.

These can me marked up as a long Markdown document:

# Page title

## Hero content
…
## Section 1
…
## Section 2
…

But this is often very limiting. We can't render sections using different templates, it’s already a stretch for documentation and can prove impossible for marketing content.

In a classical CMS, it’s common to have an object hierarchy. One "top" object or node can be rendered as a page, and it will pull bits of content from its child (or grandchild) or otherwise related objects, from a database.

But you don't need a database for that: you can have a content architecture in markdown (or other formats) and pull data from it. In Kirby CMS, you can access a page's children and render them as sections in the parent page. In Grav CMS, there are Modular pages.

This is what I’m doing with Kirby CMS:

content/
    root.txt
    1-chapter/
        chapter.txt
        1-some-section/
            section.txt
        2-other-section/
            section.txt

So we have 3 levels, rendered as 2 levels of pages:

1. A documentation index reads from children (chapters) and grandchildren (sections)
2. A documentation chapter reads from its children (sections)

Possible solutions

1. Templates could have access to a content traversal API (Content traversing of API in a template file #250) with the ability to retrieve sub-pages and their metadata. (This is what Kirby CMS does.)
2. And/or this work could be prepared for each page using a convention for modular pages. (This is what Grav does, though it can also retrieve sub-pages I believe.)

Let's describe that second option. One would need a convention for partial content or modules. For instance:

my-cool-page/
    index.md
    _part1.md
    _part2.md
    _part3.md

Or maybe with optional ordering:

my-cool-page/
    index.md
    1_some-id.md
    2_another-slug.md
    3_this-is-pretty-cool.md

Now each partial content could have its own frontmatter, and be rendered using a layout. And there might be an automatic collection of partial content (or fragments or whatever) for the my-cool-page/index.md page, which could be accessed in its template:

<h1>{{ title }}</h1>
<div class="intro">
{{ content | safe }}
</div>
<nav class="toc">
<ul>
  {% for item in fragments %}
    <li><a href="#{{ item.id }}">{{ item.title }}</a></li>
  {% endfor %}
</ul>
</nav>
{% for item in fragments %}
  <section id="{{ item.id }}">
    <h2>{{ item.title }}</h2>
    {{ item.content | safe }}
  </section>
{% endfor %}

Of course there’s a lot of overlap with a more generic traversal API, so maybe doing both is overkill, and the only useful feature would be a convention for treating pages (or "templates" in eleventy parlance) as invisible content that does not produce a HTML page but may still be accessed by the traversal API.

[zachleat]

https://fvsch.com/static-site-generators/

[kleinfreund]

That’s a use case for including content.

A root document would look like this:

multi-section-post.md:

# Multi-section Post

{% include section-1.md %}

{% include section-2.md %}

This only requires that the templating language (e.g. Liquid) is processed before transforming the Markdown.

[fvsch]

@kleinfreund How would you retrieve metadata from the included markdown files?

[Wolfr]

I was making my first project with 11ty and I thought it was weird that includes are limited to the includes folder.

For example I had a few markdown partials that I wanted to include. Now I have to put them in the general folder while they actually belong in the relevant folder.

This is my structure:

.
├── _data
│   ├── albums.json
│   ├── films.json
│   └── series.json
├── _includes
│   ├── footer.html
│   ├── games-ct.html
│   ├── games-ct.md
│   ├── layouts
│   │   ├── base.njk
│   │   └── content.njk
│   ├── nav.html
│   ├── online-video-ct.html
│   └── online-video-ct.md
├── albums
│   └── index.njk
├── disclaimer.njk
├── films
│   └── index.njk
├── games
│   └── index.njk
├── index.njk
├── onlinevideo
│   └── index.njk
└── series
    └── index.njk

I would like to put the .md files in their respective folders. Maybe I am just doing something wrong.

[zachleat]

Just for the record @Wolfr includes are not necessarily limited to the includes folder. It’s currently broken in Nunjucks though. Some more commentary at #190

[zachleat]

This repository is now using lodash style issue management for enhancements. This means enhancement issues will now be closed instead of leaving them open.

View the enhancement backlog here. Don’t forget to upvote the top comment with 👍!

[Ryuno-Ki]

I was about to open a ticket for this, but gladly searched before I did.
My use case are <aside>s. I want them to author as Markdown + Layout (Partial).
Right now I have to include the content as part of the partial :-/

[codenomnom]

Okay, guys, sorry to bring this to life after so many years. I'm struggling here and would appreciate any help 😅

I have a huge single static page website. And I want to split the content into many small pages. The reason I want pages is that:

1. I'll use the front matter for internal anchors (the slug of the page would be the anchor ID)
2. I'll use the front matter to create TOC based on the directory structure (see below)
3. Nesting would help with structuring levels and headings
4. I think that will help with translations afterward

Here's what I plan my file structure to look like:

.
└── content
    ├── index.md
    ├── chapter-1
    │   └── chapter-1.md
    ├── chapter-2
    │   ├── chapter-2.md
    │   └── section-2-1
    │       ├── section-2-1.md
    │       ├── basics1.md
    │       └── basics2.md
    └── chapter-3
        ├── chapter-3.md
        └── section-3-1
            ├── section-3-1.md
            ├── advanced1.md
            └── advanced2.md

The end content in index.html would look like:

<h1 id="content">Content Title</h1> <!-- title from content/index.md -->

<!-- children printed here -->

<h2 id="chapter-1"> <!-- slug/id from content/chapter-1/chapter-1.md -->
  Chapter 1 <!-- title from content/chapter-1/chapter-1.md -->
</h2>
<!-- no children here -->

<h2 id="chapter-2">Chapter 2</h2>

<h3 id="section-2-1">Section 2-1</h3>
<!-- content of section-2-1.md -->
basics1 <!-- content from basics1.md -->
basics1 <!-- content from basics1.md -->

<!-- ... chapter 3 -->

Because those items are actual pages, I can easily create a custom collection that follows the same structure (either by nesting or by some filtering/grouping). Then, I can easily create TOC:

{# pseudo #}
{% for page in collection.custom %}
  <a href="{{ page.id }} indent="{{ page.level }}>{{ page.title }}</a>
{% endfor %}

---

Unfortunately, I haven't had much success so far. The only thing that looks promising (and works for nested pages) is renderFile from the EleventyRenderPlugin. It works okay, but it does not support front matter 😭 I tried following the logic and creating a custom plugin for that (to modify the simple file read logic). Still, all the Template* files are not exported from Eleventy and are not easy to access. I wouldn't like to branch out just for that.

Do you have any suggestions on how to tackle that issue? Thanks in advance! 🤟

Edit: not sure how to bring the issue up from the graveyard as it's closed, so I'm pinging you directly. Sorry 😊 @zachleat

[pdehaan]

@codenomnom Probably better to file a new issue or open a new discussion, but in the past I've seen some very clever usages around using permalink: false to create complex one page sites (plus then adding some sort of order front matter key to determine which order the contents should appear on the page).

Here was my attempt at your layout: https://github.com/pdehaan/11ty-254/

tree . --gitignore -a

.
├── .eleventy.js
├── .gitignore
├── README.md
├── package-lock.json
├── package.json
├── src
│   ├── _includes
│   │   ├── advanced1.md
│   │   ├── advanced2.md
│   │   ├── basics1.md
│   │   └── basics2.md
│   ├── chapter-1
│   │   └── chapter-1.md
│   ├── chapter-2
│   │   ├── chapter-2.md
│   │   └── section-2-1
│   │       └── section-2-1.md
│   ├── chapter-3
│   │   ├── chapter-3.md
│   │   └── section-3-1
│   │       └── section-3-1.md
│   ├── index.md
│   └── src.11tydata.js
└── www
    └── index.html

8 directories, 17 files

I had to move the basics1.md, basics2.md, advanced1.md, and advanced2.md files to the _includes/ folder since I was struggling w/ ignoring front matter in an include file, but otherwise seemed pretty similar.

The entire site just creates a single /index.html file with the following:

<h1>Content Title</h1>
<section data-file-slug="chapter-1" data-order="100">
  <h2>Chapter 1</h2>
</section>
<section data-file-slug="chapter-2" data-order="200">
  <h2>Chapter 2</h2>
</section>
<section data-file-slug="section-2-1" data-order="210">
  <h3>Chapter 2 - Section 1</h3>
  <h4>Chapter 2 - Section 1 - Basics 1</h4>
  <h4>Chapter 2 - Section 1 - Basics 2</h4>
</section>
<section data-file-slug="chapter-3" data-order="300">
  <h2>Chapter 3</h2>
</section>
<section data-file-slug="section-3-1" data-order="310">
  <h3>Chapter 3 - Section 1</h3>
  <h4>Chapter 3 - Section 1 - Advanced 1</h4>
  <h4>Chapter 3 - Section 1 - Advanced 2</h4>
</section>

[codenomnom]

Hey there, thanks for the information! I was going in the same direction, but renderFile cannot go recursive.

I've managed to do what I wanted in the following way (I will write a more extended version and provide a sample shortly):

• Move each piece into its own folder/page (nested)
• Have a few computed properties (in an 11tydata file in the main content folder):
  • level - uses page.filePathStem and counts its slashes (/) to determine how deep it is from the root folder
  • parentPath - again using page.filePathStem, removing a few sections from the end (one for the file name, and one for the current page's folder, leaving with the parent folder only)
• A custom collection that has a chain of actions:
  • Get all pages
  • Group them into levels (using page.data.level). The result is an array of levels, each level containing pages: [[section1, section2], [section1.1, section1.2, section2.1], [section2.1.1, section2.1.2, section 2.1.3]]. This is crucial for the next step
  • Looping through level groups, I calculate the "order" of the pages. They are pretty similar to the one listed above - each page gets parent order + its own order. The pages are grouped by levels to ensure the parent's "order" was already calculated.
  • Flatten the array
  • Sort pages based on the newly calculated order
• At the end, I use a simple recursive render of the page, something along the lines of:

{% for page in collections.pages %}
  {% if page.data.parentPath == parent %}
    print title + content
    {% include 'printPages', parent: page.inputPath %} --> creates recursion
  {% endif %}
{% endfor %}

This way, I can print everything on one page, structured the same way the files were structured in folders. I use a few more magics to make custom ordering and indexing. Then I generate the sections dynamically (including <h{{ index}}>), which then helps me with TOC.

Thank you, I'll post an update and a working sample soon. Cheers! 🍻