Allow disabling title of reference page

[daffidwilde]

Hi there - I'm using quartodoc for a project of mine and would really like to be able to include a description on the index page.

I can't do this manually as my documentation is built and published automatically via GitHub Actions.

---

I would like to include the API reference material in a listing with titles and descriptions on my overall Reference page, but Quarto is pulling the first description it finds through. I think it would be relatively straightforward to add this functionality in at this line in Builder.write_index().

The write_index() method would look something like this (using a Quarto metadata header):

    def write_index(self, blueprint: layout.Layout):
        """Write API index page."""

        _log.info("Summarizing docs for index page.")
        content = self.renderer.summarize(blueprint)
        _log.info(f"Writing index to directory: {self.dir}")

        header = f"---\ntitle: {self.title}\ndescription: {self.description}\n---"
        final = f"{header}\n\n{content}"

        p_index = Path(self.dir) / self.out_index
        p_index.parent.mkdir(exist_ok=True, parents=True)
        p_index.write_text(final)

        return str(p_index)

You would also have to catch the description when instantiating Builder (using a blank string as deafult?). Then users could add an optional description for their API reference material with the description option in the quartodoc block of their _quarto.yml file.

Happy to fork and make a PR if the owners are open to this.

[machow]

Hey, thanks for opening this issue! What do you think of creating a custom index page for your reference? Would that resolve this issue?

https://machow.github.io/quartodoc/get-started/extending.html#using-a-custom-index-page

I'm open to #313, but worry generating a yaml top-matter with the reference might remove the flexibility of creating a custom index page.

For example, you could get something like this...

---
title: topmatter from a custom index page
---

Some stuff from a custom index page

Other custom stuff

---
title: Reference
description: a description generated as part of the reference
---

I haven't thought too much through customizing the index page, so there's likely room for quartodoc to improve here!

[daffidwilde]

Ah, I didn’t even realise that was an option… almost certainly the right tool for the job. Thank you :)

I will try things out on Monday and will close this issue and the PR if all is well.

Enjoy your weekend!

[daffidwilde]

So, I've tried the custom index page and I can't add a description without having two sets of top matter (the one with my description from the custom index page, and the one from quartodoc).

Looks like #314 is the way to go 😄 I am happy to help implement it if that would be helpful.

[machow]

Thanks for trying the custom index, and sorry it didn't quite do what you need it to 😓. Do you mind showing a bit more how you tried a custom index page? quartodoc shouldn't emit a top-matter, so I'm trying to get a sense for how you're seeing two sets of top matter. (I could just be totally wrong about quartodoc's behavior here).

It seems like this approach should produce a single top-matter with a description..

reference/index.qmd

---
description: my description
---


{{< include /reference/_api_index.qmd >}}

_quarto.yml

website:
  navbar:
    left:
      - file: reference/index.qmd
        text: Reference

quartodoc:
  out_index: reference/_api_index.qmd
  # add the rest of quartodoc config here...

[daffidwilde]

Sure thing, and thank you!

I've removed the title from the custom index top matter as you suggest, and I still have issues.

Namely, I can't see the description in the rendered page. Also, the title is listed as undefined in the listing where I want to list the API reference material. I figure Quarto extracts what it needs from the top matter if it exists, and so the title doesn't come through?

Config: /_quarto.yml[quartodoc]

quartodoc:
  title: API Reference
  package: census21api
  dir: docs/reference/api
  out_index: _index.qmd
  sections:
    - title: CensusAPI
      desc: Core class for connecting to the Census API
      package: census21api.wrapper
      contents:
        - CensusAPI

Custom index page: /docs/reference/api/index.qmd

---
description: Technical reference for the `census21api` package
---

{{< include /docs/reference/api/_index.qmd >}}

Quartodoc index: docs/reference/api/_index.qmd

# API Reference {.doc .doc-index}

## CensusAPI

Core class for connecting to the Census API

| | |
| --- | --- |
| [CensusAPI](CensusAPI.qmd#census21api.wrapper.CensusAPI) | A wrapper for the 2021 England and Wales Census API. |

Rendered API index page: /reference/api/

Rendered listing on the central Reference page: /reference/

[machow]

Oh shoot--I think this may be related to some funky edge cases in quarto, which depend on how title is set.

If you add title to the top-matter does it fix it?

---
title: API Reference
description: Technical reference for the `census21api` package
---

{{< include /docs/reference/api/_index.qmd >}}

If this is the case, and there's 1 extra title, we may need to tweak quartodoc to be able to disable setting the title using # API Reference or something......

edit: what version of quarto are you using?

[machow]

I'll add the option to set the title to null, in order to disable it