Skip to content

Use Markdown image syntax so MkDocs manages and checks image paths - #38

Open
CodyCBakerPhD wants to merge 3 commits into
aplbrain:mainfrom
CodyCBakerPhD:claude/markdown-image-syntax
Open

CodyCBakerPhD wants to merge 3 commits into
aplbrain:mainfrom
CodyCBakerPhD:claude/markdown-image-syntax

Conversation

@CodyCBakerPhD

@CodyCBakerPhD CodyCBakerPhD commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

What with the growing inclusion of images, I figured this nicety might be worth it in the CI process for this repo

Feel free to close if not desired

🤖 AI summary below 🤖

Why

A missing or misnamed image fails CI instead of shipping broken.

If Seeber2025_Fig1d.png were deleted, mkdocs build --strict (which CI runs) gives:

Version Result
raw HTML Documentation built passes, and the page ships with a broken image
This PR WARNING - Doc file '…/Suthana_Zenodo.md' contains a link '../assets/Seeber2025_Fig1d.png', but the target … is not found → Aborted with 1 warnings in strict mode!

Changes

  • mkdocs.yml: enable attr_list (for { style="width: 70%;" }) and md_in_html (so Markdown is parsed inside HTML blocks).
  • Suthana_Zenodo.md: 9 images → <figure markdown="span"> + Markdown image, the pattern Material for MkDocs documents for figures. Material centres figure contents, so the inline display:block; margin: auto centring is no longer needed.
  • embervault-uploading-data.md: 11 images → Markdown images. The lettered lists stay raw HTML (<ol type="a">) but gain markdown on the <ol> and markdown="span" on each <li>. Both levels are needed: with it only on the <ol>, the images come out as literal […] text.
  • Fix the Fig. 4 original image's alt text, which said Figure3_original.

Cost

Two new Markdown extensions, and the markdown attributes on the Vault page's HTML lists, which are a small thing for future editors to know about. Rendering is unchanged.


🤖 Generated with Claude Code

https://claude.ai/code/session_01U3AaCyMTCHNwo9aUwupg4L

Convert the images on the Suthana example and EMBER-Vault upload pages
from raw <img> tags with hand-written relative paths to Markdown images
with doc-relative paths. MkDocs rewrites these for each page's output
URL, so they keep working if a page moves or use_directory_urls changes,
and mkdocs build --strict fails if one points at a missing file.

Enable attr_list (to keep the width styling) and md_in_html (so Markdown
is parsed inside the existing <figure> and <ol type="a"> blocks). Also
correct the Fig. 4 alt text, which said Figure3.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U3AaCyMTCHNwo9aUwupg4L
main moved the EMBER-Vault Account Setup section out of
embervault-uploading-data.md into a new embervault-account.md. Resolve
the conflict by taking main's version of that part of the page; the
image it contained is converted on its new page in the next commit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DQrzw4cByPMdPKT3Cizkwk
main added raw <img> tags to index.md and embervault-account.md with
root-absolute /assets/... paths. Those resolve on docs.emberarchive.org,
which is served from the domain root, but break on PR previews, which
are served under /pr-preview/pr-N/, and mkdocs build --strict does not
check them. Use doc-relative Markdown images instead, like the rest of
this branch.

On index.md the figures are nested HTML, so mark each level with
markdown so the image inside is parsed, and bring the nested lines to
the left margin: indented four or more spaces inside a markdown block,
they would render as a code block. The innermost div uses
markdown="span" so the image is not wrapped in a <p>, which keeps the
page rendering pixel-identical to main. The commented-out panels get
the same treatment so they work if uncommented.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DQrzw4cByPMdPKT3Cizkwk
@github-actions

Copy link
Copy Markdown

🚀 Preview for this pull request is published at

https://aplbrain.github.io/bbqs-ember-docs-previews/pr-preview/pr-38/

Built from 65151cf to gh-pages in aplbrain/bbqs-ember-docs-previews. Updates on every push; not removed when the pull request closes.

@CodyCBakerPhD CodyCBakerPhD changed the title Use Markdown image syntax so MkDocs manages and checks image paths- #7 Use Markdown image syntax so MkDocs manages and checks image paths Oct 28, 2026

This branch has not been deployed

No deployments
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.

2 participants