[feature] Use Material theme for docs

[daenney]

Description

• I have no strong feelings about this change. Feel free to close it. I just thought I'd give it a go and see what it turned into
• I haven't updated the Conda environment.yml yet but I'll go fight with it if this is a change you want to merge

This changes the theme to use Material with the slate (dark) theme and the accent colour set to orange. It also replaces the swagger plugin with one that works correctly with the Material theming.

I mostly tinkered with this because the Material theme provides a number of enhancement that make the docs easier for me personally to consume:

• Content is in the middle of the screen, instead of pinned to the left (especially annoying on widescreen)
• Scales nicer/is more usable at higher zoom levels
• The document outline in the right hand column is much more obvious and accessible than tucked into the menu
• With the built-in colours you can get closer to something that feels like the GTS style, and with a custom palette we can make it match perfectly in the future

Potentially useful in the future:

• The social cards plugin/feature is nice to generate the fancy card previews
• Maintains a Docker container (with all dependencies) that makes it easy to generate the website allowing it to be hosted anywhere

To try it locally:

$ python3 -m venv .venv
$ .venv/bin/pip install -r docs/requirements.txt
$ .venv/bin/mkdocs serve

It ends up looking like this currently:

Checklist

Please put an x inside each checkbox to indicate that you've read and followed it: [ ] -> [x]

If this is a documentation change, only the first checkbox must be filled (you can delete the others if you want).

• I/we have read the GoToSocial contribution guidelines.

[daenney]

You can preview the built version here now: https://gotosocial--1535.org.readthedocs.build/en/1535/

[f0x52]

ooh very nice! let me see if I can quickly port our colorscheme :)

[f0x52]

./mkdocs.yml:

  palette:
    scheme: gotosocial
extra_css:
  - assets/colors.css

./docs/assets/colors.css:

[data-md-color-scheme="gotosocial"] {
	--md-primary-fg-color: #fd6a00;
	--md-default-fg-color: #fafaff;
	--md-default-fg-color--light: var(--md-default-fg-color);
	--md-default-fg-color--lighter: var(--md-default-fg-color);
	--md-default-fg-color--lightest: var(--md-default-fg-color);
	--md-default-bg-color: #2a2b2f;
	--md-default-bg-color--light: #35363b;
	--md-default-bg-color--lighter: #3a3b41;
	--md-default-bg-color--lightest: #4d4e56;

	--md-typeset-color: var(--md-default-fg-color);
	--md-typeset-a-color: #66befe;
	--md-accent-fg-color: #89caff;

	--md-footer-bg-color: var(--md-default-bg-color);
}

.md-content {
	background: var(--md-default-bg-color--lightest);
}

[igalic]

is there a light theme for that as well?

[daenney]

./mkdocs.yml:

  palette:
    scheme: gotosocial
extra_css:
  - assets/colors.css

./docs/assets/colors.css:

[data-md-color-scheme="gotosocial"] {
	--md-primary-fg-color: #fd6a00;
	--md-default-fg-color: #fafaff;
	--md-default-fg-color--light: var(--md-default-fg-color);
	--md-default-fg-color--lighter: var(--md-default-fg-color);
	--md-default-fg-color--lightest: var(--md-default-fg-color);
	--md-default-bg-color: #2a2b2f;
	--md-default-bg-color--light: #35363b;
	--md-default-bg-color--lighter: #3a3b41;
	--md-default-bg-color--lightest: #4d4e56;

	--md-typeset-color: var(--md-default-fg-color);
	--md-typeset-a-color: #66befe;
	--md-accent-fg-color: #89caff;

	--md-footer-bg-color: var(--md-default-bg-color);
}

.md-content {
	background: var(--md-default-bg-color--lightest);
}

Amazing, thank you! I'll add that to the PR ❤️

[daenney]

is there a light theme for that as well?

There is. Material also allows you to enable switching between dark and light. However, since GTS itself doesn't have a light theme (that I know of) and my goal was to make it feel more as part of the project I haven't looked into that.

[daenney]

@f0x52 Your changes are awesome but it interacts a bit poorly with the Swagger UI (if you go into API Documentation > API Documentation). Things become a bit difficult to read. Any chance you can come up with a fix for that?

[f0x52]

@daenney ahh right, forgot to check that page. Will give it a look this afternoon.

@igalic there's currently no light GoToSocial colorscheme, but will also be something I'll look into soon(tm) (also #1214). When it's there for normal GTS it should be easy to port to the docs as well

[daenney]

For the Swagger UI, here's:

• Plugin: https://github.com/blueswen/mkdocs-swagger-ui-tag
• Dark theme comes from: https://github.com/Amoenus/SwaggerDark/

[tsmethurst]

@f0x52 feel free to merge this when you're happy with it, it doesn't need to be before 0.7.1, since the docs at docs.gotosocial.org are always built from main anyways :)

[daenney]

Just one thing, I haven't updated the Conda environment yet. I'll try and figure that out today.

[daenney]

I think the Conda file is correct now. The dependencies listed make sense at least.

[daenney]

Card generation works now. So if you were to link the Federation page, in places that show the card previews you'll see [

[f0x52]

Had to rename the theme back to "slate" because that's what https://github.com/Amoenus/SwaggerDark/ is hardcoded to detect dark mode 🙄
also re-added the "default" theme as a light-mode option (not GTS-colored for now). Good to merge I think!

[daenney]

Had to rename the theme back to "slate" because that's what https://github.com/Amoenus/SwaggerDark/ is hardcoded to detect dark mode roll_eyes also re-added the "default" theme as a light-mode option (not GTS-colored for now). Good to merge I think!

Ah well that's annoying. I might look into fixing that. But some other day.

If you're happy with the changes then lets do it 😄