Add new index-landing layout

[LisaFC]

Create a layout for generating "index-type" landing pages in docs sections, eg with a list of all the topics in a particular section.

[LisaFC]

Demo of same: https://serene-roentgen-10fbaa.netlify.com/docs/adding-content/

[LisaFC]

@chenopis @RichieEscarez @sarahmaddox @jaredbhatti does this seem like something we should add to the theme, versus just having in the example site?

[sarahmaddox]

It'd be great to have it in the theme.

For Kubeflow, I ended up creating my own layout: https://github.com/kubeflow/website/blob/master/layouts/docs/list.html Which replaces this rudimentary layout in the theme: https://github.com/google/docsy/blob/master/layouts/docs/list.html

My layout needs work, in that it doesn't do a good job of handling the situation where a section includes single pages as well as other sections. See this index page for example - the links point to a mix of single pages and sections, which is not clear and the ordering is funny: https://www.kubeflow.org/docs/pipelines/

Your layout is much prettier. Does it handle a mix of subsections and single pages? :)

[LisaFC]

Yes it does! It doesn't do anything particularly exciting with them in that it won't show that a topic link is a full-blown section rather than a single page, but they do end up in the right order, and I think that's probably the behaviour we want for now rather than having a full nested menu on the landing page?

The other question is whether we want both sorts of landing page (ie the one without the index, which is list.html, and the one that has it, which is list-landing.html) in the theme, and should we demo them both in the example site?

[sarahmaddox]

Re:

Yes it does! It doesn't do anything particularly exciting with them in that it won't show that a topic link is a full-blown section rather than a single page, but they do end up in the right order, and I think that's probably the behaviour we want for now rather than having a full nested menu on the landing page?

Sounds good!

The other question is whether we want both sorts of landing page (ie the one without the index, which is list.html, and the one that has it, which is list-landing.html) in the theme, and should we demo them both in the example site?

I'd say just the list-landing.html, to avoid confusion. I think an opinionated Docsy is a good Docsy. :) But I'd love to hear what others think.

[RichieEscarez]

Opinionated sgtm. Does that require adding a "description" the frontmatter? How does it render without?

Options wise, maybe down the line we can have a section about how to modify default behaviors?

For Knative, i copied some of the nav code and into a partial and then use a conditional to check if a "landing" page is empty/blank. If nothing has been added through a "readFile" shortcode, then we show a list of pages and sections (in order and nested) but w/o descriptions.

Partial

Example

[LisaFC]

So if you don't have a description in your front matter, you just don't get a description, there's just the blue link to the page/section.

Let me play around with it a bit in terms of what happens if we use it for a section where we don't want a list/index....

[LisaFC]

OK, I have parameterameterameterized it so that you can have

• no list
• simple list with bullets (I totally stole this from Istio)
• nice list with descriptions (default)

Which do we think should be the default?

[sharifsalah]

Your suggested default (nice list with descriptions) sounds good to me.

[LisaFC]

OK, I'll do a PR and then update the example site to use it in various permutations.

[LisaFC]

I don't think it'll break anything if we make the nice list behaviour the default - @markmandel, it looks like you've already created a listy landing page type to override the existing one for Agones, and for other users the worst that will happen is people will get a list of subpages under their landing page contents. This might be a case for @RichieEscarez' suggestion about update notes/release notes, though...