[docs] Anchors in Markdown?

Destry · 2016-09-05 15:14:09

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.

gaekwad · 2016-09-05 15:25:56

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

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

…and then link to it:

[soft, yellow fruit](#banana)

Any good?

gaekwad · 2016-09-05 15:32:36

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)

Destry · 2016-09-05 15:33:34

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.

Destry · 2016-09-05 15:34:21

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

Destry · 2016-09-05 15:36:58

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

gaekwad · 2016-09-05 15:38:57

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>

gaekwad · 2016-09-05 15:39:33

Crossed in transit again. Glad it worked!

Destry · 2016-09-05 15:43:37

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?

gaekwad · 2016-09-05 16:06:10

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

philwareham · 2016-09-05 16:21:20

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.

philwareham · 2016-09-05 16:24:34

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.

hcgtv · 2016-09-05 20:57:06

Destry,

Is the official tag reference using Textpattern?

If it is, it sure looks like duplication of effort to me.

Maybe you missed the memo that was circulating?

jakob · 2016-09-05 22:06:55

hcgtv wrote #301077:

Destry,

Is the official tag reference using Textpattern?

I don’t think it is anymore. The latest version is I believe maintained on github and built with jekyll. It should still be possible to bring it over to txptags, though?

BTW: on a side note, I’d love to see a phpxref of the new 4.6 branch. Things have changed quite a bit since 4.5.7.

hcgtv · 2016-09-05 22:27:47

jakob wrote #301082:

BTW: on a side note, I’d love to see a phpxref of the new 4.6 branch. Things have changed quite a bit since 4.5.7.

Yes, they have. When I have the chance, I’ll zip up the 4.6 CrossRef and provide you a link.

Textpattern CMS

Textpattern CMS support forum

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