New web stack POC

[agardnerIT]

Hi all,

I spent some time translating the docs to mkdocs.

This now runs easily with mkdocs serve.

It can be build with mkdocs build

It can be auto-deployed to GitHub pages with mkdocs gh-deploy

As I've stated elsewhere, I'm happy to help maintain the docs.

What are the projects thoughts on moving to this as it seems much more maintainable.

[AntoineThebaud]

That looks great! Personally the 2 main issues I have with the current doc is:

• Not enough nesting allowed https://github.com/perses/website/issues/23
• Pages within a same section are ordered by their title alphabetically, which is too restrictive (you may want to have an "Introduction" coming first then a "Conclusion" for instance :D)

I dont know much the current framework though, maybe these could be solved somehow.. but by any chance does your mkdocs-based website solve these 2 problems?

Could you share more screenshots of the different sections?

[agardnerIT]

1. Yes, nesting is arbitrary.
2. Yes, ordering is set by you in nav of mkdocs.yml

The nav section of mkdocs.yaml

nav:
  - 'Home': 'index.md'
  - 'Docs':
      - 'docs/index.md'
      - 'Authentication': 'docs/authentication.md'
      - 'DAC':
        - 'X': 'docs/dac/something.md'
        - 'Page One': 'docs/dac/index.md'
  - 'Demo': 'https://demo.perses.dev'

[AntoineThebaud]

Great! Btw does it support switching Perses versions easily like we have currently?

[Nexucis]

It can be auto-deployed to GitHub pages with mkdocs gh-deploy

For the moment the website is served on a VM behind a reverse proxy (traefik) that helps to ensure we have a proper certificat for the DNS perses.dev.

Will it be possible to keep this way ?

[Nexucis]

Are you able to support the mermaid schema ? Just to know if it will help to fix the current issue https://github.com/perses/website/issues/30

[Nexucis]

Great! Btw does it support switching Perses versions easily like we have currently?

would be so cool to be able to fix https://github.com/perses/website/issues/13 with this change

[agardnerIT]

Versioning

Yes: https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning

See here: https://agardnerit.github.io/persesdocpoc

Check the gh-pages branch of this repo. Each docset is pushed to a dedicated folder. index.html does the redirect and versions.json is the reference list.

The commands are:

mike deploy 0.2 --push
# When ready to make 0.2 the "latest" version
mike set-default 0.2 --push

Serving

Yes. mkdocs build ultimately translates HTML + markdown to static files.

You can host those static files however / wherever you like. FWIW Github pages allows setting a custom domain so that could be an option should you wish to retire that VM.

Diagrams

Yes: https://squidfunk.github.io/mkdocs-material/reference/diagrams/

[Nexucis]

Awesome, that sounds good for me. Thank you for answering all the questions we have !

@AntoineThebaud @nicolastakashi are you also to move forward on this and migrate to mkdocs ?

[nicolastakashi]

Hey! @agardnerIT thanks for handling that. I've been thinking about the same thing, especially after spend a lot of time upgrading template and not having any success, customization on docs is being very trick, we've been using it in Prometheus Operator but the template is not very flexible.

I'm good for this adoption, especially because mdoks using material theme is a very nice experience, I'm using it internally on my company to another matters.

I'd love to know how I can support with on this journey.

[Nexucis]

great ! thank you for your quick response @nicolastakashi !

@agardnerIT please let us know how we can help you to make this migration, and thank you for proposing it ! 🙏

[agardnerIT]

I’ll start working on this. Should we lift and shift the docs “as-is” or take the opportunity to “split” the user journey path into two sides:

1. Perses the dashboard spec path
2. Perses “the tool”

1 would cater towards other vendors and those who wish to support the DAC spec (import Perses config and translate to vendor, support exporting to Perses format etc.)

2 would cater for those who wish to use Perses as a product

[Nexucis]

I would start to migrate as is.

In the meantime, I would be curious about what do you have in mind exactly when you are talking about splitting.

I'm curious, because for the moment, the dashboard spec is quite clear from my perspective as it is described in the API specification. But as I have literally written it, I don't have a fair point of view :)

[Nexucis]

By the way, when performing the changes, could you also add the Linux Foundation footer please ? This is part of the https://github.com/cncf/toc/issues/1411 tasks:

Ensure LF footer is on your website and guidelines are followed (if your project doesn't have a dedicated website, please adopt those guidelines for the README file).

Would be cool if it's possible to have it !

[nicolastakashi]

I agree with @Nexucis about this as is change. Regarding docs rebrand if you want we can talk to our website mantainer on the prometheus operator, he did a very nice job and maybe might have some experience to share.

[Nexucis]

Also in my Christmas list, it will be interesting to have a place for blog post or at least be able to reference external blog post. 👼

We could start by this one: https://horovits.medium.com/unveiling-perses-the-gitops-friendly-metrics-visualization-tool-f05b5324d7da.

I think Dotan makes a great introduction about Perses :)

[agardnerIT]

Thanks all. I'm arranging KCD Sydney this week but I'll get on this next week.

The material theme does indeed look like they have blog capabilities but for speed, I'll add a "Resources" page where we can (to start) just link out to external content.

I'll lift and shift as-is for speed + add the LF banner.