Markdown and linkable section headers

  • Unknown's avatar
    jmegner · Member ·

    I was at blogspot and got tired of the limited and awkward functionality. I want to do my blog posts in markdown for ease and portability. In wordpress, doing an entire post inside a markdown block seems to be most of what I want. I think the biggest remaining thing is linkable section headers. I want to be able to link to headers in the markdown block with [display text](#name-of-anchor-for-header) but I have not figured out a way to do it.

    I can’t do # Linkable Section 1 {:#linkable-section-1} like this says. I can’t get embedded HTML to work, so # Linkable Section 2<a name="linkable_section_2"></a> does not work. Section headers by themselves also do not generate ids to link to (unlike GitHub).

    Doing a header block with a HTML anchor does work, but then that means interleaving markdown and non-markdown blocks, and I was hoping for pure markdown.

    https://jacobegner.wordpress.com/2023/05/31/wordpress-test/ shows the results of my attempts.

    How can I get linkable headers within a markdown block?

    The blog I need help with is: (visible only to logged in users)

  • staff-95percentghost · Staff ·

    Hi! I’ve been having a hunt for the relevant information, but I’m not too sure if anchors within the Markdown block are available at this time. It uses the CommonMark spec, for reference:
    https://spec.commonmark.org/0.30/

    Our guide for the Markdown block is here in case of need:
    https://wordpress.com/support/wordpress-editor/blocks/markdown-block/

    The WordPress.org document regarding markdown to create header anchors doesn’t look like it uses the same markdown spec as the Markdown block, though I haven’t directly been able to find what spec it does use; however I did send a quick message to the team who handle the Markdown block to ask if there was anything we’re missing with regards to creating anchors with the block as it is now and otherwise ask if it’d be viable to bring those in.

    As it is, all blocks are still HTML behind the scenes; typically each block has a comment around it which doesn’t appear in the final markup on the published page; so the block markup for a header with an anchor looks like this in the code editor view too:

    <!-- wp:heading {"anchor":"heading-1"} -->
<h2 class="wp-block-heading" id="heading-1">heading</h2>
<!-- /wp:heading -->

    I do understand you’d find it smoother to do everything within Markdown, but I did want to reassure you that the block/HTML side of things wouldn’t be incompatible if you did wish to export posts which have both heading blocks and Markdown!

    One thing I’m wondering, especially if you’re planning to do something like setting up a few headers to have anchors, is whether our Table of Contents block might be useful. I did test to be sure so I should note: it doesn’t look like it can automatically generate page anchors from Markdown headers, but for regular heading blocks it does speed up the page anchor process.

  • Unknown's avatar
    jmegner · Member ·

    I did send a quick message to the team who handle the Markdown block to ask if there was anything we’re missing with regards to creating anchors with the block as it is now and otherwise ask if it’d be viable to bring those in.

    Great, thank you.

    One thing I’m wondering, especially if you’re planning to do something like setting up a few headers to have anchors, is whether our Table of Contents block might be useful…it doesn’t look like it can automatically generate page anchors from Markdown headers

    The TOC block looks really cool if I were to do a post with heading blocks. I look forward to it working with markdown headers.

  • jmills39 · Staff ·

    Hello there,

    Yes, the TOC Block provides a nice experience for people to navigate your content.

    Regarding the Markdown Block, we confirmed with one of our teams that it doesn’t support header anchors at the moment. However, you could use the Heading Block to use heading anchors like this screenshot demonstrates:

    Heading Block:
    https://wordpress.com/support/wordpress-editor/blocks/heading-block/

    Our support documentation is also an excellent resource for WordPress.com-specific guidance:
    https://wordpress.com/support/

    If you need any help setting up your blog or want to share more about what you’d like to accomplish with a new site here, please let us know so we can share personalized recommendations.

    Did you already own a domain from your previous site that you would like to use with your new one? If so, you can do that with any of the paid hosting plans or even get a custom domain free for the first year with an annual plan.

    WordPress.com Plan Comparison:
    https://wordpress.com/pricing/

    Please feel free to reply to this message if you have any other questions and have a great day!

  • The topic ‘Markdown and linkable section headers’ is closed to new replies.