Update instructions about adding a tutorials folder to a project

[heitortsergent]

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:

• In Publish your tutorial the instructions says to create a tutorial page under docs/sources, but it should be under docs/sources/<VERSION>.
• In Before you begin, the instructions show a code snippet with some front matter properties. In the k6-docs case, we didn't have multiple targets in that part of the front matter, so when I copy+pasted that snippet, the build stopped working. It would be nice to have a longer snippet, maybe:

cascade:
  - _target:
      path: /docs/<PROJECT>/*/tutorials/**
    _build:
      list: false
      render: false
  - _target:
      path: /docs/<PROJECT>/**
      ...

[jdbaldry]

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]

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]

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.