Resolve local images everywhere + staticFiles + sitemap.xml#341
Merged
Conversation
Add a pure buildSitemapXml(siteUrl, basePath, slugs) and emit sitemap.xml at the output root when RenderOptions.siteUrl is set — one <loc> per non-hidden page, so hidden source-viewer pages are excluded. Only siteUrl's origin is used; the deploy sub-path comes from theme.basePath, so the two never double-count. Register siteUrl in utils' RenderOptions and THEME_OPT_KEYS.
… and comments Only opts.docs images were copied into the build before. Route local images referenced from tutorials, the README, and JSDoc-comment prose through the same content-hashed _assets/ pipeline (Markdown and raw <img>), resolving comment images against each doclet's own source file. Also: - Honor templates.default.staticFiles: copy the included files verbatim to the output root (JSDoc parity), and treat the include dirs as fallback search roots so a bare reference such as  resolves and is hashed. A file already served from _assets/ is not duplicated at the root. - Skip image syntax inside code spans / fenced blocks / <pre>/<code>, so example syntax shown in prose is left literal (no spurious copy or warning). - Thread opts.siteUrl through to render() for sitemap.xml.
Mirror the JSDoc bridge in the TypeDoc plugin: resolve README and symbol-comment images through the shared content-hashed _assets/ pipeline (handling raw <img> and skipping code regions), and emit sitemap.xml when cleanJsdocTheme.siteUrl is set.
basic: add an img/ directory, a "Working with Images" tutorial, a JSDoc-comment image, a README image, templates.default.staticFiles.include, and siteUrl. typedoc-basic: add a doc-comment image and siteUrl.
Add the "Working with Images" guide (en + hi/ja/zh) covering image resolution across docs, tutorials, README, and JSDoc/TypeScript comments, plus templates.default.staticFiles. Document the siteUrl option on the configuration page in every locale, enable siteUrl on the docs-site itself, and update ARCHITECTURE for the image pipeline, staticFiles, sitemap, and code-region skip.
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.
Fixes #333.
Summary
Local image assets now work from every prose source the theme renders, not just
opts.docs— plus JSDocstaticFilessupport and a generatedsitemap.xml. Both the JSDoc and TypeDoc bridges have parity.Image resolution
_assets/pipeline and the reference is rewritten — both Markdownand raw<img>. Comment images resolve against each symbol's own source file; SVGs are inlined (theme-toggle-aware).templates.default.staticFilesis honored: included files are copied verbatim to the output root (JSDoc parity), and the include directories become fallback search roots, so a bare reference likeresolves and is hashed — no need to rewrite existing comments/tutorials. A file already served from_assets/isn't duplicated at the root.<pre>/<code>is left literal — no spurious copy, rewrite, or "could not read image" warning.sitemap.xml
siteUrland the build emitssitemap.xmlat the output root — one<loc>per non-hidden page (hidden source-viewer pages excluded). Only the URL's origin is used; the deploy sub-path comes frombasePath, so the two never double-count.Docs & examples
siteUrldocumented on the configuration page in every locale; enabled on the docs-site itself.examples/basicandexamples/typedoc-basicgain fixtures exercising each path.ARCHITECTURE.mdupdated for the image pipeline,staticFiles, sitemap, and the code-region skip.Tests
examples/basic,examples/typedoc-basic, the docs-site (all locales build with zero image warnings), and a real consumer project.Commits
feat(dwar)— emit sitemap.xml from the rendered page setfeat(clean-jsdoc-theme)— resolve images from tutorials / README / comments, staticFiles, code-region skipfeat(typedoc)— image-resolution parity + siteUrltest(examples)— image, staticFiles, and siteUrl fixturesdocs— Working with Images guide, siteUrl docs, ARCHITECTURE