Add project website

[ll-nick]

Hosting a static website via github.io shouldn't be a huge amount of effort but is way cooler than having just the readme.

[orzechow]

There's a ton of tools for Markdown to Webpage generation. Most render the markdown file(s) to a static HTML page

• pro: fast and robust website
• con: needs some kind of CI/CD (GitHub Workflow)
• pro/con: usually needs distinct doc files

Some render the Markdown even fully on the client side via JavaScript

• pro: no compilation necessary
• pro: one can simply use an existing Readme.md
• con: slower on the client side and might be less robust

A (somewhat arbitrary) collection:

Vitepress

• Starship.rs uses Vitepress to generate their beautiful website
• Simple Markdown header defines theme, metadata etc.
• GitHub Pages deployment

MKDocs

• root mkdocs.yml defines theme, metadata etc.
• a lot of themes
• GitHub Pages deployment

zero-md (based on marked)

• client side rendering
• very simple usage
• nice default theme

[orzechow]

I'd first try it with zero-md, as this could bring a really nice efford/result tradeoff :grinning:

[orzechow]

I briefly tried out zero-md and GitHub Pages directly.

Turns out zero-md provides the theme and rendering for the markdown page in itself, but does not layout an appropriate page container. For a use case as ours, is intended to be used together with zero-md-docs. That again assumes the whole docs to be placed in /docs

As a result, the zero-md only page looks like this


---

GitHub also features rendering of the Markdown Pages with a GitHub renderer directly and provides a selection of themes. External themes can be used as well. As this allows reusing the root Readme.md I gave it a shot with the Cayman theme

Without any more styling to the Cayman theme, this is how our Page looks.


I'd change colors, hero background image etc. but overall I like the theme regarding page layout, font etc.

[orzechow]

See

• https://github.com/KIT-MRT/arbitration_graphs/pull/50

[orzechow]

@ll-nick How do you like the Cayman theme?

[ll-nick]

Ah, I see you've been busy :)

Yes, I looked through all the themes just now and I agree that the Cayman one looks best. Using a statically generated site via GitHub actions also seems like the sensible choice to me.

So how would it work for the tutorial? Can you create sub pages using more markdown files and have some kind of navigation bar or something?

[orzechow]

So how would it work for the tutorial? Can you create sub pages using more markdown files and have some kind of navigation bar or something?

Yepp, linking to the respective Markdown file (e.g. in /docs) works :tada: See

• https://github.com/KIT-MRT/arbitration_graphs/pull/51

I'm impressed – that's like no effort at all :heart:

[orzechow]

Alright, I played around with colors, fonts and code highlighter themes.

That's my best approach


These changes are still in the generic cayman theme repo (was the easiest to setup for testing): orzechow/cayman@style_for_arbitration_graphs

So, I still need to transfer this to our page.

@ll-nick Are you fine with the theme?

[ll-nick]

Look great! :heart:

[orzechow]

Alright, PR is ready: #50