Skip to content

docs: split the README into docs/, and document the dashboard - #52

Merged
xiaodoudou merged 3 commits into
masterfrom
docs/restructure
Sep 22, 2026
Merged

xiaodoudou merged 3 commits into
masterfrom
docs/restructure

Conversation

@xiaodoudou

Copy link
Copy Markdown
Owner

The README was 527 lines, 133 of them changelog. Anyone arriving at the repo had to scroll past every setting to find out what the thing was.

Now 123 lines: what it does, how to start, where the docs are, why it exists.

Reference material moves to docs/, a page per subject, and the changelog to CHANGELOG.md.

The dashboard had no documentation at all, having been written after the last README pass. docs/dashboard.md covers the generated password and why it goes to the console rather than the log, setting your own, what the page shows, and that auth deliberately does not cover the endpoints Plex calls.

Two things worth flagging:

  • Every internal link and anchor was checked after the split, including ones that used to be same-page anchors and are now cross-file.
  • docs/security.md was silently untracked. The SECURITY.md ignore rule for your local notes was not root-anchored, so it matched at any depth and, on a case-insensitive filesystem, matched docs/security.md too. The README link to it would have 404'd on GitHub. Now anchored; the local notes are still ignored.

The README had grown to 527 lines, of which 133 were changelog and most of the
rest was reference material. Anyone arriving at the repository had to scroll
past every setting to find out what the thing was.

It is now 123 lines: what it does, how to start, where the documentation is,
and why it exists. The reference moves to docs/, a page per subject, and the
changelog to CHANGELOG.md where tooling expects it.

The dashboard had no documentation at all, having been written after the last
README pass. docs/dashboard.md covers the generated password and why it goes to
the console rather than the log, choosing your own, what the page shows, and
that authentication deliberately does not cover the endpoints Plex calls.

Every internal link and anchor was checked after the split, including the ones
that used to be same-page anchors and are now cross-file.
The rule exists to keep local security notes out of the repository, but it was
not anchored, so it matched at any depth and, on a case insensitive filesystem,
matched docs/security.md too. The page was silently left untracked and the link
to it from the README would have been a 404 on GitHub.

Anchored to the root. The local notes are still ignored.
The prose was wrapped at roughly 78 columns, which markdown ignores when it
renders but which makes the source annoying to edit: changing a word reflows
the paragraph. Paragraphs are now one line each. Fenced blocks, lists and
tables keep the line breaks they need, and the changelog keeps its wrapping
because it lives inside a fence.

The pages I wrote also read like documentation written by committee, which
is to say every sentence explained itself. The dashboard page and the several
providers section are rewritten to sound like someone telling you how the
thing works. Your original text is left as it was.
@xiaodoudou
xiaodoudou merged commit a527759 into master Sep 22, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant