Skip to content

docs: standardise README and add docs/ - #999

Merged
willtheorangeguy merged 1 commit into
mainfrom
docs/content
Aug 22, 2026
Merged

docs: standardise README and add docs/#999
willtheorangeguy merged 1 commit into
mainfrom
docs/content

Conversation

@willtheorangeguy

Copy link
Copy Markdown
Owner

Brings willtheorangeguy.github.io in line with the Wave 2 documentation contract.

Read this first: src/pages/projects.astro hardcodes image URLs into other repositories' docs/images/ directories, which this sweep is deleting in favour of willtheorangeguy/.github/icons/. One of those images is already broken and twelve more break as the other open PRs merge. Every replacement already exists centrally. Details and the full list are in docs/internal/known-issues.md; nothing in src/ is changed here.

README — rewritten to the house template. The logo used a github.com/.../blob/ URL, which serves an HTML page rather than image bytes, so the repository's front page opened with a broken image; both images now come from .github/icons/. The Discord badge and link are dropped, and ## Changelog and ## You may also like... are removed.

docs/README.md (index), quickstart.md, installation.md, usage.md (renamed from USAGE.md and rewritten around writing posts rather than only running the site), configuration.md, architecture.md, development.md, deployment.md, faq.md, troubleshooting.md, roadmap.md, and internal/known-issues.md. google-maps-automation.md is kept as it was.

  • docs/images/ is removed — both files already exist in .github/icons/willtheorangeguy.github.io/.
  • docs/google-maps-stats.md was a tracked empty file, written by nothing and linked from nowhere. Deleted.
  • docs/legal/PRIVACY.md and TERMS.md are renamed to lowercase, and their Contact Us links given a scheme — both read ](github.com/...), which Markdown resolves as a relative path, so the one link a reader follows to make a data request was a 404.

Findings — eight, recorded in docs/internal/known-issues.md:

  • The Projects page points at other repositories' docs/images/ (High), with the per-repository status listed.
  • The documented docker run -p 8000:80 maps a port nothing listens on (Medium) — nginx/nginx.conf has listen 8080.
  • The README logo used a blob/ URL (Medium). Corrected.
  • Two lockfiles are committed and only pnpm's governs CI (Medium), while the Dockerfile runs an unlocked npm install.
  • docs/google-maps-stats.md was a tracked empty file (Low). Deleted.
  • CLAUDE.md describes a build pipeline missing the Storybook step and calls the site Astro 6 where package.json pins Astro 7 (Low).
  • PLANNING.md is a three-line stub pointing at retired classic Projects (Low).
  • The legal documents' contact links had no scheme (Low). Corrected.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TtaJBmFDK3GcSyuhSuZ84R
@willtheorangeguy
willtheorangeguy merged commit 8c9ab61 into main Aug 22, 2026
11 checks passed
@willtheorangeguy
willtheorangeguy deleted the docs/content branch August 22, 2026 05:33
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