grafana / writers-toolkit

Technical documentation guidelines for Grafana Labs documentation
https://grafana.com/docs/writers-toolkit/
21 stars 14 forks source link

Update instructions about adding a tutorials folder to a project #816

Closed heitortsergent closed 1 month ago

heitortsergent commented 2 months ago

In the Tutorials topic type page, there are a few instructions that I think need to be updated as I was following along to try to add the tutorials folder to the k6-docs repository:

cascade:
  - _target:
      path: /docs/<PROJECT>/*/tutorials/**
    _build:
      list: false
      render: false
  - _target:
      path: /docs/<PROJECT>/**
      ...
jdbaldry commented 2 months ago

It sounds like you managed to work around the documentation confusion.

Unfortunately, this mostly arises from the non-standard way we have set up k6-docs. In every other repository, the tutorials are in docs/sources/tutorials because the branch itself is the version. In k6-docs, we keep all versions in main. We could probably clarify that in our Writers' Toolkit docs too.

For the hiding the tutorials cascading front matter, do you have the snippet that worked in k6-docs? I am perhaps thinking that the instructions should specify that the front matter should go in the project's root index file which is often in the website repository (but is docs/sources/_index.md for k6-docs)

heitortsergent commented 2 months ago

Ah, you're right about the docs/sources/tutorials, sorry about that @jdbaldry! I had just looked at the path for adding tutorials in the manual_mounts property and assumed other projects also had it under a version folder.

About the front matter snippet, this is what we had in k6-docs:

cascade:
  labels:
    products:
      - oss
  breadcrumb_start: 4
  search_section: Grafana k6
  search_type: doc
  public_docs: true
  github_repo: https://github.com/grafana/k6-docs/
  github_branch: main
  github_dir: /docs/sources
  replace_dir: docs/k6/
  JSLIB_AWS_VERSION: 0.12.3

So when I added the snippet from the writers-toolkit, this is what it looked like (and it broke the build):

cascade:
  labels:
    products:
      - oss
  breadcrumb_start: 4
  search_section: Grafana k6
  search_type: doc
  public_docs: true
  github_repo: https://github.com/grafana/k6-docs/
  github_branch: main
  github_dir: /docs/sources
  replace_dir: docs/k6/
  JSLIB_AWS_VERSION: 0.12.3
  - _target:
    path: /docs/k6/*/tutorials/**
    _build:
      list: false
      render: false

And then I looked at the other repos and figured out I just needed to add another _target property:

cascade:
  - _target:
    path: /docs/k6/**
    labels:
      products:
        - oss
    breadcrumb_start: 4
    search_section: Grafana k6
    search_type: doc
    public_docs: true
    github_repo: https://github.com/grafana/k6-docs/
    github_branch: main
    github_dir: /docs/sources
    replace_dir: docs/k6/
    JSLIB_AWS_VERSION: 0.12.3
  - _target:
    path: /docs/k6/*/tutorials/**
    _build:
      list: false
      render: false
jdbaldry commented 2 months ago

Aha! Yeah that makes complete sense. I can definitely add a note about that. It's confusing because Hugo allows two forms, as you now know. The standard is just a mapping of values that applies to every page, the second option is an array of those mappings with specific targets.