Skip to content

Commit 2e65f15

Browse files
committed
Document prettier-ignore rule for kramdown abbreviations
Prettier mangles kramdown abbreviation syntax (*[ → _[), silently destroying every <abbr> in the post; both format-md and the pre-commit hook run Prettier. The fix convention (a preceding <!-- prettier-ignore --> per contiguous block) lives only in one post, so record it in the content-authoring reference where the jekyll-site-dev skill will surface it for future posts.
1 parent b06192b commit 2e65f15

1 file changed

Lines changed: 20 additions & 0 deletions

File tree

.claude/skills/jekyll-site-dev/references/content-authoring.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,3 +42,23 @@ Simple formatting tags for non-book creative works. Emit
4242

4343
Accepts quoted strings or Liquid variables (`{% game_title page.title %}`).
4444
Base class: `ui/tags/cite_title_tag.rb`.
45+
46+
## Kramdown Abbreviations Need Prettier Protection
47+
48+
Kramdown abbreviation definitions (`*[CERN]: European Organization...`)
49+
are not CommonMark, and Prettier rewrites `*[` to `_[`, which kramdown
50+
does not recognize — every `<abbr>` silently disappears and the
51+
definitions render as literal text. Both `make format-md` and the
52+
pre-commit hook run Prettier, so any abbreviation block **must** be
53+
preceded by `<!-- prettier-ignore -->`:
54+
55+
```markdown
56+
<!-- prettier-ignore -->
57+
*[CERN]: European Organization for Nuclear Research
58+
*[CMS]: Compact Muon Solenoid
59+
```
60+
61+
The comment protects one contiguous block (a single CommonMark node).
62+
Keep all definitions together with no blank lines between them; a
63+
second block separated by a blank line needs its own comment. The only
64+
current use is `_posts/2018-05-20-my_phd_thesis.md`.

0 commit comments

Comments
 (0)