Documentation website

[micahflee]

Addresses #374.

• Design docs website with docusaurus
• Write docs for 1.0.28
• Finish making search work
• Write version 1.0.28 docs
• Host site at docs.cyd.social
• Update docs to include Bluesky in next version
• Finish first development blog post
• Update all links in the Cyd app itself to point to new docs links instead of old cyd.social links
• Update old cyd.social docs links to redirect to the new docs website, and in general redo the content now that we have docs (I'll do this after this PR is merged)

Right now, the website https://docs.cyd.social/ is configured to pull and build docs from this PR branch, but once it's merged we can update it to pull docs from the main branch. But for now, you can read the docs from there.

Docs for the latest version: https://docs.cyd.social/docs/intro/
Docs for the upcoming version: https://docs.cyd.social/docs/next/intro

How to manage docs

As we're developing features we can update the docs in docs/docs -- this will update the upcoming version (/docs/next/*.

The current version is 1.1.x, so if we need to update the docs in this version, we can do that by editing docs/versioned_docs/version-1.1.x.

This way, we can keep the current version (1.1.x for now) relatively static, and the upcoming version can constantly change and get automatically updated as we merge PRs into main.

When we're making a new big release (e.g. when we move from 1.1.x to 1.2.x) and the docs are finished and frozen, we can tag a new version to freeze the docs. This will make it so https://docs.cyd.social/docs/intro/ will point to the newer version (1.2.x), and https://docs.cyd.social/docs/next/intro will point to whatever docs are in the main branch.

New development blog

In addition to documentation, there's now a dev blog with a blog post for the 1.1.0 release: https://docs.cyd.social/blog/cyd-1.1.0

This adds a step to our stable release checklist: write a dev blog post about it. Note that we may need to update the date of this blog post depending on if we make the release tomorrow or not.

When reviewing:

• Read through the feature icons/items on the docs homepage and give feedback if you have any.
• Please read through every page of the docs, and also the dev blog post.
• Check for typos or ways things could be improved to be less confusing, etc.
• I'm also interesting in anything that's missing.

[SaptakS]

Read through the feature icons/items on the docs homepage and give feedback if you have any.

I am not fully convinced we need that page. It feels redundant with cyd.social. If we want to have a page like that, instead of the icons and descriptions, I would have links to different sections of docs such as "Getting started" "Tips" "Development Blog" etc. Otherwise it feels to me like an extra step to go to the docs.

[SaptakS]

I have not read through the entire documentation, but one thing that I notice is link colors don't meet color contrast requirements. Also, I usually prefer having body text links to be underlined, to help color blind users distinguish between links and non link texts.

The other thing is, I would add aria-hidden=true for all the icon svg such as the home icon in breadcrumb, or the dark mode switch. Though if it's too complicated it's not super necessary.

And honestly, I am not too happy about the fact that it shows a blank screen when JS is disabled. I would have prefered the project do some form of progressive enhancement, where people using browsers with JS disabled can still see the content.

[SaptakS]

This color is being used for the document links, and this color doesn't have enough contrast against a white background. We need something darker.

[micahflee]

Can you suggest better colors to replace these with?

:root {
  --ifm-color-primary: #4986c9;
  --ifm-color-primary-dark: #3b6ea3;
  --ifm-color-primary-darker: #315b85;
  --ifm-color-primary-darkest: #26476a;
  --ifm-color-primary-light: #5a9bd4;
  --ifm-color-primary-lighter: #6faedc;
  --ifm-color-primary-lightest: #a5c3e4;
  --ifm-code-font-size: 95%;
  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
  --ifm-color-secondary: #ffc663;
  --ifm-footer-link-hover-color: #ffeed1;
}

/* For readability concerns, you should choose a lighter palette in dark mode. */
[data-theme='dark'] {
  --ifm-color-primary: #a5c3e4;
  --ifm-color-primary-dark: #8fb0d1;
  --ifm-color-primary-darker: #7a9cbb;
  --ifm-color-primary-darkest: #6687a5;
  --ifm-color-primary-light: #b7d0e9;
  --ifm-color-primary-lighter: #c8dced;
  --ifm-color-primary-lightest: #d9e8f1;
  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
  --ifm-color-secondary: #ffc663;
  --ifm-footer-link-hover-color: #ffeed1;
}

[redshiftzero]

docs look great! a few small nits inline but otherwise LGTM from my side

[micahflee]

Okay, I have done the following:

• Ripped out the homepage and made it redirect straight into the docs
• Made body links have underlines
• In light mode, made link colors darker
• Fixed typos

I didn't do these:

• I couldn't immediately find a way to add a <noscript> block, so when loading the page without JS it's still just white. But the good news is, I tested it in Tor Browser with the security slider to Safest and it actually all works fine
• I also couldn't figure out how to add aria-hidden=true to the SVGs

changed

[SaptakS]

I actually tested the live docs site, and it seems to be working in firefox with JS disabled. Maybe it's progressively enhanced once it is built and hosted? Not sure.