How can I get the effects of both _index.md and index.md?

support
1

Hi,

I apologise if this has been asked before but it’s a difficult problem to search about.

Some background info: I’m building a website with a docs section for software/package/API documentation. The hierarchy for this is Project -> Version -> Topic (for example, “Hello World” -> “1.x” -> “Installation”). To reflect this, I have the following structure under my content directory:

content/
    docs/
        hello-world/
            1.x/
                index.md
                configuration.md
                extending.md

Additionally, I have three taxonomies defined - projects, versions and topics. Every docs page has one term for each of those defined, e.g.:

---
projects: "Hello World"
versions: "1.x"
topics: "Installation"
---

When viewing a project’s docs, I have a sidebar containing a list of topics and the pages that fall under them. In order to limit the versions and topics shown based on the current project (and version in the case of topics), I have a docs.html template that I’m using specifically for documentation content:

{{ partial "header.html" . }}

<div class="documentation">
  {{ partial "top.html" . }}

  <section class="header">
    <h1>{{ .Params.Projects }} {{ .Params.Versions }} Documentation</h1>
    <h2>{{ substr .Params.Topics 3 }} - {{ .Title }}</h2>
  </section>

  <section class="content">
    <div class="wrapper">
      <aside>
        <div class="version-select">
          {{ $projectPage := .Site.GetPage (printf "/docs/%s" ($.Params.projects | lower | urlize)) }}

          {{ $versions := slice }}
          {{ range $projectPage.Pages.Reverse }}
            {{ $versions = $versions | append .Params.versions }}
          {{ end }}
          
          <div class="current-version">Version <span>{{ .Params.versions }}</span> <img src="/images/caret_down.svg"></div>

          <ul class="versions">
            {{ range $versions | uniq }}
              <li><a href="{{ $projectPage.Permalink }}{{ . }}/" {{ if eq . $.Params.versions }}class="active"{{ end }}>{{ . }}</a></li>
            {{ end }}
          </ul>
        </div>

        <ul class="topic-select">
          {{ range .Site.Taxonomies.topics }}
            {{ $pages := where (where .Pages.ByWeight ".Params.projects" $.Params.projects) ".Params.versions" $.Params.versions }}
          
            {{ if gt (len $pages) 0 }}
              <li class="separator" data-content="{{ substr .Page.Title 3 }}"></li>

              {{ range $page := $pages }}
                <li>
                  <a href="{{ $page.Permalink }}" {{ if eq $page.Permalink $.Permalink }}class="active"{{ end }}>
                    {{ $page.Title }}
                  </a>
                </li>
              {{ end }}
            {{ end }}
          {{ end }}
        </ul>
      </aside>

      <main>
        {{ .Content }}
      </main>
    </div>
  </section>
</div>

{{ partial "footer.html" . }}

This works, but I have a new problem; if I use index.md instead of _index.md, that index page is listed in the sidebar but other pages in the same bundle aren’t (in the {{ range $page := $pages }} loop above). If I use _index.md instead, the other pages are listed, but that index page isn’t. In order to have both, I have to use both files, duplicating the content (even if both contain the same front matter, if one of them has no content, it invariably results in a page with no content).

I suppose my question is twofold; 1) is there a better way of achieving what I’ve done so far and 2) how can I get my docs list template to output all pages, including the index, without having to duplicate it?

Thanks!

2

The “Suggested Topics” for this one pointed me towards a solution. Instead of using either _index.md or index.md, I’m explicitly setting the URL in the page that I want to behave as the index, e.g. in /content/docs/hello-world/1.x/introduction.md I have url: "/docs/hello-world/1.x/". It’s not perfect but it seems to do what I need, so I’ll roll with that. :slightly_smiling_face: