Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: Add resource files #38

Open
jdbaldry opened this issue Jun 27, 2024 · 2 comments
Open

feat: Add resource files #38

jdbaldry opened this issue Jun 27, 2024 · 2 comments

Comments

@jdbaldry
Copy link
Member

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
Copy link
Member Author

jdbaldry commented Jun 27, 2024

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:

Information common to both pages.

Information unique to the Killercoda page.

@jdbaldry
Copy link
Member Author

jdbaldry commented Jul 2, 2024

User interface is more complicated than expected, as documented in #49

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant