Go to main content

Textpattern CMS support forum

You are not logged in. Register | Login | Help

#1 2016-09-05 15:14:09

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,912
Website

[docs] Anchors in Markdown?

In the sleffort (slog effort) to convert new docs from Textile to Markdown, most of the pages I edited employ an in-page ToC, for example. No problem with Textile, but how do you set such anchors with Markdown? Or do we lose those ToCs and the affordance they provide to page usability.

Offline

#2 2016-09-05 15:25:56

gaekwad
Server grease monkey
From: People's Republic of Cornwall
Registered: 2005-11-19
Posts: 4,276
GitHub

Re: [docs] Anchors in Markdown?

Try this (untested) – make your anchor in the document:

<a name="banana"></a>

…and then link to it:

[soft, yellow fruit](#banana)

Any good?

Offline

#3 2016-09-05 15:32:36

gaekwad
Server grease monkey
From: People's Republic of Cornwall
Registered: 2005-11-19
Posts: 4,276
GitHub

Re: [docs] Anchors in Markdown?

Something else to try – again, untested, and my Markdown is very rusty.

Some implementations of Markdown generate implicit anchors with headers, so this:

## Ingredients

…would have an ID/anchor of #ingredients. I think that linked text without an explicit target auto-links to its namesake anchor:

[Ingredients][]

…links to #ingredients. Your mileage may vary.

Last edited by gaekwad (2016-09-05 15:33:09)

Offline

#4 2016-09-05 15:33:34

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,912
Website

Re: [docs] Anchors in Markdown?

Sorry, I wasn’t clear. How do you target a header?

So if my ToC link item is:

[Attributes](#atts)

How to I target that to an <h2>, for example.

Offline

#5 2016-09-05 15:34:21

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,912
Website

Re: [docs] Anchors in Markdown?

Ah, cross-posting. I’ll try that.

Offline

#6 2016-09-05 15:36:58

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,912
Website

Re: [docs] Anchors in Markdown?

Yep, that works. Thanks. That also ensures an exact match between ToC item and header label, which could be beneficial.

Offline

#7 2016-09-05 15:38:57

gaekwad
Server grease monkey
From: People's Republic of Cornwall
Registered: 2005-11-19
Posts: 4,276
GitHub

Re: [docs] Anchors in Markdown?

ToC:

# Fruit
  * [Apple](#a)
  * [Banana](#b)
  * [Cherry](#c)

Target headers:

## Apple <a id="a"></a>

## Banana <a id="b"></a>

## Cherry <a id="c"></a>

Offline

#8 2016-09-05 15:39:33

gaekwad
Server grease monkey
From: People's Republic of Cornwall
Registered: 2005-11-19
Posts: 4,276
GitHub

Re: [docs] Anchors in Markdown?

Crossed in transit again. Glad it worked!

Offline

#9 2016-09-05 15:43:37

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,912
Website

Re: [docs] Anchors in Markdown?

Oh, fark! There’s all kinds of footnotes and tables… This will take a year just to convert the little progress I actually made with docs before.

Do we really need to do this?

Offline

#10 2016-09-05 16:06:10

gaekwad
Server grease monkey
From: People's Republic of Cornwall
Registered: 2005-11-19
Posts: 4,276
GitHub

Re: [docs] Anchors in Markdown?

What can we do, Wion-san? Divvy up the work between some worker elves?

Offline

#11 2016-09-05 16:21:20

philwareham
Core designer
From: Haslemere, Surrey, UK
Registered: 2009-06-11
Posts: 3,564
Website GitHub Mastodon

Re: [docs] Anchors in Markdown?

Hi.

You don’t need to make an anchor – Jekyll does that automatically for each heading within a doc. All you need to do is:

# Article

On this page:

* [Syntax](#syntax)
* [Attributes](#attributes)
* [Something else](#something-else)

## Syntax

Blah

## Attributes

Blah blah

## Something else

Blah blah blah

Hope that helps.

Offline

#12 2016-09-05 16:24:34

philwareham
Core designer
From: Haslemere, Surrey, UK
Registered: 2009-06-11
Posts: 3,564
Website GitHub Mastodon

Re: [docs] Anchors in Markdown?

Destry wrote #301069:

Do we really need to do this?

If you mean convert to Markdown? Then yes we do. GitHub are dropping Textile from Jekyll anytime now (initially they said by May 2016 but it seems to have a stay of execution). This GitHub announcement came out of the blue without prior discussion. I know it’s annoying but it’s out of our hands.

Offline

Board footer

Powered by FluxBB