Repository navigation
docs: add user guides and correct plugin references - #393
Merged
Merged
Conversation
Pages move from docs/docs/ to docs/src/content/docs/ and images from docs/docs/resources/ to docs/public/resources/, unchanged. The repo README points at the new image paths because Obsidian's plugin browser renders it.
Each page gets title and slug frontmatter. Leading H1s move into title. Relative .md links and resources/ image paths become site-absolute, and em-dashes become plain dashes. No other content changes.
docs/ becomes a standalone npm package (own package-lock.json) that builds with Astro Starlight into docs/dist. Every URL the MkDocs site served stays the same, and /sitemap.xml redirects to /sitemap-index.xml. - A build-time check fails when a page has no slug: frontmatter, so URLs such as /QuickAdd/ cannot silently change case. - starlight-links-validator fails the build on a broken internal link or anchor. - starlight-llms-txt writes llms.txt files, and every page is also served as raw markdown at <page-url>.md. - docs:build installs and builds the docs package; wrangler.jsonc and docs:deploy publish docs/dist.
The Documentation workflow sets up Node from .nvmrc with the docs lockfile as the npm cache key, and also runs when package.json or .nvmrc change. Dependabot tracks the docs npm package instead of pip. The release workflow no longer installs Python or the deleted requirements file.
The schema rejects a page without slug: at load time, in builds and in astro dev, so the custom config-time file scan goes. Also drops the twitter:card entry Starlight already emits, types the raw-markdown endpoint props, and removes a .gitignore line the root node_modules rule covers.
# Conflicts: # package.json
# Conflicts: # .github/dependabot.yml # .github/workflows/documentation.yml
starlight-llms-txt pulls braces through micromatch, and every braces release is affected by GHSA-vfj7-8cjw-p6xm (high, no patch), which fails the required Dependency Review check. Two small endpoints now write /llms.txt (every page in sidebar order, linked as raw markdown) and /llms-full.txt from the same page markdown as /<page>.md. The sidebar moves to src/site.mjs so the config and the endpoints share one page order.
…rser Starlight's code highlighter (@expressive-code/core) pins postcss-nested 6, whose postcss-selector-parser 6.1.4 is affected by GHSA-rj75-hqrm-r3gf (moderate; fixed in 7.1.6). postcss-nested 7 only drops Node 12-16 and depends on the 7.x parser. The built site is byte-identical with and without the override, and npm audit in docs/ reports no vulnerabilities. Drop the override once expressive-code moves to postcss-nested 7.
llms.txt and llms-full.txt list pages from the sidebar, so a page left out of it would silently drop out of both while still serving its raw .md. The site title also moves into src/site.mjs next to the description and sidebar.
Starlight drops a hyphen differently from MkDocs on two headings, and moving four H1s into frontmatter removed their ids, so six old section links landed at the page top. Empty <div id> anchors restore them, and the raw markdown endpoints strip the anchors. scripts/legacy-fragments.mjs checks every heading id from master's MkDocs build (legacy-fragments.json, 73 ids) against each new build and fails the docs build when one has no target.
# Conflicts: # package.json
Empty <div id> anchors at the top of a page became its first block, so the first paragraph took Starlight's 16px block gap and the page shifted down. Old page-title ids now come from a legacyTitleId frontmatter field that a PageTitle override wraps around the title, and old section ids are empty spans inside their headings. Both land exactly where the new ids do and add no space.
# Conflicts: # AGENTS.md # package.json
Deploying podnotes with
|
| Latest commit: |
61b0b03
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://60794810.podnotes.pages.dev |
| Branch Preview URL: | https://docs-content-reference.podnotes.pages.dev |
# Conflicts: # AGENTS.md # docs/README.md # docs/package.json # docs/src/content/docs/api.md # docs/src/content/docs/commands.md # docs/src/content/docs/templates.md # docs/src/content/docs/timestamps.md # docs/src/site.mjs # docs/wrangler.jsonc # package.json
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Users can now find first-run, mobile, FAQ, and device-sync guidance in the sidebar. The template, timestamp, command, and API references match merged plugin behavior.
Fixes #352. Targets
masterafter #362 merged.Reference corrections cover the supported date/time token subsets, escaped titles and URLs, sanitized names, empty local-file stream tags, tag scopes, path limits, and the default feed-note link. Commands now include Reorder Queue, IDs, availability, exact settings names, and the separate editor/headset capture behavior. API docs include current Episode fields, missing members, numeric bounds, transcript reads, and formatting failures. URI docs cover parameters, aliases, validation, and title-match limits.
Private-feed guidance includes storage failures and undetected path tokens. Sync guidance describes the shipped snapshot behavior and private-feed reference limits. #388 is still open, so its proposed merge behavior is omitted. Source-based follow-ups are tracked in #390 and #391.
Sources are pinned to merged
origin/masterat0b9f605. Rechecked against96093b9after merging master. Thesrc/tree is unchanged between these commits, and #388 remains open.Sources per page:
Verification
61b0b03736730a1464808560a254d45522ca75b2after merging master. Fromdocs/,npm run docs:buildandnode scripts/legacy-fragments.mjs checkpassed.npm run lint,npm run format:check,npm run typecheck, andnpm run buildall passed.npm run testpassed with zero Svelte errors/warnings and 1,296 tests in 84 files.npm run docs:buildpassed with 15 pages, valid internal links, and all 73 legacy fragments.61b0b03. Walked all eight changed pages at 1440×1000 and 390×844 on the Cloudflare preview. All 76 internal URLs and fragments resolve. All four new pages appear in the sidebar. An independent Opus review passed the master integration and current sync wording.This docs-only change adds no new Obsidian runtime test. The cited mobile checks used Obsidian 1.14.4 and PodNotes 2.21.1 on an Android 14 Pixel 6 emulator. They do not establish iOS, physical-phone, or headset delivery support.
Scope
Documentation and sidebar only. Existing URLs and legacy fragments are preserved.