Skip to content

fix: remove {#id} heading attributes and ::: blocks the site does not render - #686

Merged
Ibochkarev merged 2 commits into
modxorg:3.xfrom
Ibochkarev:docs/fix-unsupported-markdown
Oct 23, 2026
Merged

Ibochkarev merged 2 commits into
modxorg:3.xfrom
Ibochkarev:docs/fix-unsupported-markdown

Conversation

@Ibochkarev

@Ibochkarev Ibochkarev commented Oct 23, 2026 •

Copy link
Copy Markdown
Collaborator

Description

The site's Markdown renderer does not support two constructs that recent pages used, so these pages show raw markup on the live site.

Headings with {#id}

The renderer has no heading-attributes extension. {#id} stays in the heading text and becomes part of its anchor: ## Database caching {#database-caching} gets the anchor #database-caching-database-caching. Links to these headings did not resolve.

Six headings are fixed, in en/ and ru/ of:

  • extending-modx/caching/index.md
  • extending-modx/tutorials/using-custom-database-tables.md

The links to them now use the anchors the site builds from the heading text, including the two links from extending-modx/caching/lifetimes.md. The Russian anchors are transliterated the way the site does it, e.g. #programmnoe-polzovatelskoe-keshirovanie.

::: warning

The site renders GitHub alerts (> [!NOTE], > [!WARNING], …) and not ::: container blocks. The one remaining ::: warning, in es/building-sites/tag-syntax/date-formats.md, is now > [!WARNING], like its English page.

Checks

  • No heading with {# and no ::: block left in en/, ru/, es/, nl/ on 3.x. The 2.x branch has none either.
  • Every anchor link in the changed pages resolves. Checked by rendering the pages with DocsApp's own Markdown setup and heading slugifier.
  • markdownlint-cli@0.18 on the changed files and validate-frontmatter.py: no issues.

Not checked

  • Not checked on a running DocsApp instance, only with its renderer and slugifier classes.
  • Other broken anchor links in the set, mostly in translated pages and in old Confluence-style links, are out of scope here and will come in a separate PR.

Affected versions

3.x. The 2.x branch has no {#id} headings and no ::: blocks.

Relevant issues

… support

DocsApp does not parse heading attributes: {#id} was shown in the heading
text and folded into its anchor, so links to these headings did not resolve.
Point the links at the anchors the site builds from the heading text.
…lert

The site does not parse ::: container blocks, so the warning showed as plain
text with the ::: markers. Use the > [!WARNING] alert the site renders.
@Ibochkarev
Ibochkarev merged commit f93e865 into modxorg:3.x Oct 23, 2026
2 checks passed
@Ibochkarev
Ibochkarev deleted the docs/fix-unsupported-markdown branch October 23, 2026 02:24
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.

1 participant