Provide more advanced documentation template

[tomkerkhove]

Explore a more advanced Jekyll theme which provides better navigation as a sidebar now that our documentation is becoming bigger.

With this change, we'll transition our docs from promitor.io to docs.promitor.io

Requirements

• Backwards compatability
• Versioned docs
• Navigation bar
• Search box

Task list

• Setup POC
• Publish alpha docs on docs-v2.promitor.io
• Provide new docs in https://github.com/promitor/docs
• Migrate legacy docs to https://github.com/promitor/legacy-docs
• Cleanup docs in this repo
• Update guidance in repo for contributions, getting started, etc.

[smholvoet]

Looks like this is no longer limited to just Jekyll, and you're considering Hugo as well?

I have some experience with both SSG's and might give this one a shot. I personally think Hugo is slightly better, and migrating from Jekyll doesn't seem to be too bad. I feel like Hugo is becoming increasingly popular (uses Go) and ticks all the boxes. Using Hugo combined with the Docsy theme could be a great combo (and is being used by Dapr for example).

Let me know what you think 🤓.

[tomkerkhove]

Hi @smholvoet - Thanks for reaching out and Hugo is definitely fine for me, I'm using it already for https://changelog.promitor.io!

Docsy sounds good to me, but I was wondering if we could introduce a "product landing page" on promitor.io and redirect all current docs to docs.promitor.io/{uri} where uri can be an exact match or another one.

This is because I want to reshuffle the documentation to make it feel more natural, but without breaking any links.

Is that possible?

[smholvoet]

So a single landing page (promitor.io), which has links to the actual docs ( docs.promitor.io/{uri})?

I'm guessing that would need two seperate build commands, similar to what's mentioned here, I don't really have any experience with that kind of setup.

I could go ahead and fork the current repo to see how things would look like in Hugo (+ Docsy) if that's ok with you.
Search functionality and a navbar would definitely be a big improvement.

[tomkerkhove]

💯, thank you!

[tomkerkhove]

I have introduced a landing page on https://promitor.io and am now publishing docs on docs.promitor.io.

Feel free to let me know how I can help you for porting docs over to Docsy @smholvoet !

[tomkerkhove]

Any thoughts if you are still wanting to pick this up @smholvoet ?

[smholvoet]

@tomkerkhove Definitely, been busy with other stuff, but I'll try and throw something together by the end of this week.

[tomkerkhove]

Oh no worries and take your time! Make sure to open a PR during hacktoberfest so you are rewarded for it as well!

[smholvoet]

I'm sure you're enjoying the great weather in 🇧🇪 as well @tomkerkhove 💨🌧️ . A perfect time to mess around with Hugo / docsy in other words.

I've created a basic Hugo directory structure and ported over a couple of pages of the current docs. I've created a Static Web App which you should be able to access here: https://agreeable-hill-07db88603.azurestaticapps.net/:

I would consider this more of a PoC, to give you an idea of how things could look like. It is in no way complete and will have things like broken links and other good stuff, so please don't mind that. Below I've highlighted a couple of features and/or things which came to mind when I was porting over content from the current docs.

Theme

I'm using the Docsy theme which looks really good if you ask me and paired with Hugo has stuff like breadcrumb navigation, a nice sidebar on the left (as well as one on the right which detects the Markdown headers), "Copy code" buttons, "last edited" annotations.

I had some issues with the Docsy submodule which is why I pushed everything to a separate repo from scratch and why the navbar color in the screenshot compared to the demo site differs. Will have to look into that further. Let me know whether you like the shade of green in the above screenshot. I matched color codes with the shade of green on the current promitor.io site.

Algolia search

Obviously not yet enabled on the demo site, but Algolia search is really powerful and honestly works great. Might also be completely free as they seem to support open source projects 🎉

Sidebar

As you can see only the "How It Works" and "Metrics" will have actual content. The current documentation "tree" is a bit... much 😄

I would be in favor of splitting up the documentation into more separate markdown files in subfolders, instead of linking to headers in a single lengthy markdown file. Have a look at how the metrics section is split up. This would make things a bit more organized and honestly works better with the sidebar.

👉 Let me know how you feel about the demo site and whether I should look into porting over further content.

[tomkerkhove]

I'm sure you're enjoying the great weather in 🇧🇪 as well @tomkerkhove 💨🌧️ . A perfect time to mess around with Hugo / docsy in other words.

That's for sure 😄

I've created a basic Hugo directory structure and ported over a couple of pages of the current docs. I've created a Static Web App which you should be able to access here: agreeable-hill-07db88603.azurestaticapps.net:

I would consider this more of a PoC, to give you an idea of how things could look like. It is in no way complete and will have things like broken links and other good stuff, so please don't mind that. Below I've highlighted a couple of features and/or things which came to mind when I was porting over content from the current docs.

Love it!

Theme

I'm using the Docsy theme which looks really good if you ask me and paired with Hugo has stuff like breadcrumb navigation, a nice sidebar on the left (as well as one on the right which detects the Markdown headers), "Copy code" buttons, "last edited" annotations.

This is exactly what I've had in mind, I've found that this theme is great for this kind of docs so thanks a ton!!!

I had some issues with the Docsy submodule which is why I pushed everything to a separate repo from scratch and why the navbar color in the screenshot compared to the demo site differs. Will have to look into that further. Let me know whether you like the shade of green in the above screenshot. I matched color codes with the shade of green on the current promitor.io site.
What colors can we use? It can just be black if that's easier as well? I don't have much of a preference to be honest.

Algolia search

Obviously not yet enabled on the demo site, but Algolia search is really powerful and honestly works great. Might also be completely free as they seem to support open source projects 🎉

💘

Sidebar

As you can see only the "How It Works" and "Metrics" will have actual content. The current documentation "tree" is a bit... much 😄

I would be in favor of splitting up the documentation into more separate markdown files in subfolders, instead of linking to headers in a single lengthy markdown file. Have a look at how the metrics section is split up. This would make things a bit more organized and honestly works better with the sidebar.

👉 Let me know how you feel about the demo site and whether I should look into porting over further content.

Agreed! I would suggest to move everything over as-is and then we can improve the whole structure maybe? What do you think?

I like this to visualize things, btw, and would can ideal for listing scrapers:

[tomkerkhove]

Thanks a ton btw! If you are up for it, I'd love to see it move forward and happy to introduce docs-vnext as a new folder to consolidate it so that you can make changes gracefully and we can easily swap - Thoughts?

[smholvoet]

Sounds good to me, I'll add all of my stuff to a dedicated folder.

[tomkerkhove]

@smholvoet Any thoughts if you are able to pick this up? If not, no problem and I can take over!

Thanks anyway for what you have done already!

[smholvoet]

@tomkerkhove

I've actually recently been busy setting up a technical docs site for an internal team using mkdocs. Combined with the material theme, it makes for a great pairing. You can see a live example here. I've spent quite some time setting it up and I personally found it it be a lot easier to get things up and running than with Hugo. Feature wise, I'd say their pretty similar, especially looking at the things I've summed above (a decent theme, Algolia search, sidebar, ...).

Regarding Algolia (which is awesome), they seem to have a DocSearch program you can apply for, which makes things free.

Your call of course, let me know whether you personally prefer Hugo over mkdocs and I'll see what I can do, but might need some help here and there. If you choose to go the mkdocs route, I can get things working a lot quicker. Both of them will be a step up from the current docs site.

[tomkerkhove]

That sounds good to me as well - Both have a good way of structuring docs and making them accessible!

So if you are up for it then I'm all game, but don't feel obliged of course! And if you do, don't feel the need to move everything over. If the foundation is there with some examples then I'm happy to do the majority of the 🐒 work.

[smholvoet]

Looking for some input on the navigation tabs feature.

When tabs are enabled, top-level sections are rendered in a menu layer below the header for viewports above 1220px, but remain as-is on mobile.

Made a quick mock-up with navigation.tabs disabled:

navigation.tabs enabled:

Note: the left navbar looks a bit empty in the above screenshot, but will contain the "subtopics" of that specific main menu item (similar to the first screenshot)

Let me know which one you prefer. Having it enabled shows the main "sections" a bit clearer (especially if you have lots of topics in your navbar on the left), whilst having it disabled makes things a bit cleaner imo.

[tomkerkhove]

That's a tough one but I'd go with the tabs on top given there's a lot of content and we can improve the overall structure a bit more by doing that in my opinion. Thoughts?

PS: Does it support "versioned docs"?

[smholvoet]

Tabs on top (navigation.tabs enabled) is fine. I was planning on reworking the structure a bit anyway (=more dedicated folders containing separate markdown file instead of linking to sections in a single MD file).

In regards to versioning: entirely possible 👉 see Setting up versioning.

[tomkerkhove]

Perfect - Thanks!

[smholvoet]

I've created a draft PR which adds the mkdocs config file (mkdocs.yml) to root of the rep, as well as the new structure (docs-vnext folder), so still a WIP.

You can find a preview here 👉 https://brave-mushroom-0de444803.azurestaticapps.net/

[tomkerkhove]

Awesome, thanks!

[tomkerkhove]

First rough version without full parity is merged in to /docs-vnext and published through Netlify on http://docs-v2.promitor.io/

[tomkerkhove]

Things to do, see issue description.

[tomkerkhove]

Everything is being moved to https://github.com/promitor/docs

[tomkerkhove]

All current docs have been ported to http://docs-v2.promitor.io/, all feedback is welcome on what can be improved