Repository navigation
feat: README images reach the site, and GitHub alerts render as callouts - #4
Merged
Merged
Conversation
A homepage rendered from README.md kept the README's repo-root paths, so <img src="docs/images/logo.svg"> pointed at <base>/docs/images/logo.svg while :asset-dirs copies docs/images to <base>/images. Links that start with docs/<entry>/ or ./docs/<entry>/ for a configured entry now point at that copy. Anything else is left as written. A blockquote opening with [!NOTE], [!TIP], [!IMPORTANT], [!WARNING] or [!CAUTION] rendered as a plain quote showing the marker. It now renders as GitHub does, a div.markdown-alert with a title, styled from the existing syntax colours so it follows the light and dark themes. Found on champaca's site, whose README has both.
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
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.
Two things champaca's site got wrong on its README homepage, both fixed in the engine so any project with the same README shape gets them.
README images
A homepage rendered from
README.mdkept the README's paths, which are relative to the repository root. Champaca's README shows its logo with<img src="docs/images/logo.svg">, which is right on GitHub. On the site it resolved to/champaca/docs/images/logo.svg, a 404, because:asset-dirs ["images"]copiesdocs/imagesto/champaca/images.generic-home/rewrite-readme-asset-linksnow pointssrcandhrefvalues that start withdocs/<entry>/or./docs/<entry>/at<site-base>/<entry>/, for each configured:asset-dirsentry, in either quote style. That covers raw HTML<img>, markdown![]()and plain links. A path into a directory that isn't listed is left as written, since the build doesn't copy it. Guide pages aren't touched: their../images/xpaths already resolve.GitHub alerts
> [!WARNING]rendered as an ordinary blockquote starting with the literal[!WARNING].markdown/github-alertsnow renders the five GitHub kinds (NOTE, TIP, IMPORTANT, WARNING, CAUTION, any case) as GitHub does:div.markdown-alert.markdown-alert-<kind>with ap.markdown-alert-title. The colours reuse the syntax-highlighting tokens, so the callouts follow the light and dark themes, with the dark value as a fallback before the head script setsdata-theme.It works on the rendered HTML, which has two differences from GitHub, noted in the docstring:
> [!TIP] texton one line becomes an alert here but stays a quote on GitHub, and a blockquote nested inside an alert ends the alert early. A marker inside a code block is never touched, because markdown-clj has already escaped it.Checked
bb test: 110 tests, 286 assertions, 0 failures (107 before). The new tests cover all five kinds plus a lowercase marker, a plain quote, an unknown marker and a fenced block left alone, and a README homepage built end to end with raw-HTML, markdown and./image paths, a link, and an unlisted directory.README.mdanddocs/, with:asset-dirs ["images"]added, built and served:/champaca/images/logo.svgand/champaca/images/champaca-1880.jpgreturn 200 (image/svg+xml,image/jpeg), and the warning renders as a callout with no[!WARNING]text left.The README documents both. Champaca itself still needs the one-line
:asset-dirs ["images"]in itsdocs/site.edn, which its own session will add.