grafana / killercoda

This repository holds tutorials designed and hosted on Killercoda and interactive education platform.
https://killercoda.com/
Apache License 2.0
2 stars 4 forks source link

feat: Add resource files #38

Open jdbaldry opened 5 days ago

jdbaldry commented 5 days ago

So I got this situation in a tutorial: I'm giving people a really long docker-compose.yml listing, and asking them to run it.

I can tell them to copy it into a file, but that's no fun.

I can commit it as a separate file to the KC repo, but that's no fun, because if someone modifies the docs, we now have 2 sources of truth for the docker-compose file that need to stay in sync.

What I'd really like to say is:

<!-- INTERACTIVE resource "docker-compose.yml" START -->
version: '3'
services:
  loki:
    image: grafana/loki:3.0.0
    ports:
      - "3100:3100"
      - 
    command: -config.file=/etc/loki/local-config.yaml
<!-- INTERACTIVE resource "docker-compose.yml" END -->

You can guess what that would do.

Image

jdbaldry commented 5 days ago

I'm not sure if we have guidance for this yet but in the Loki quickstart, resource files are fetched from the source repository in a task step: https://github.com/grafana/killercoda/blob/staging/loki/loki-quickstart/step1.md?plain=1#L13-L19.

Any content in the source documentation needs to be ignored by Hugo to prevent it being rendered on the website. At the moment, the only mechanism is putting everything in HTML comments but that means every line of of the included content needs to be within a comment: https://github.com/grafana/killercoda/blob/staging/docs/transformer.md?plain=1#L213-L227.

Perhaps a Hugo shortcode that ignores its contents would make that more ergonomic:

```markdown
Information common to both pages.

{{< docs/ignore >}}
Information unique to the Killercoda page.
{{< /docs/ignore >}}

Produces:

```markdown
Information common to both pages.

Information unique to the Killercoda page.
jdbaldry commented 19 hours ago

User interface is more complicated than expected, as documented in https://github.com/grafana/killercoda/pull/49