Textile Markup Tip 1 - Creating an Anchor on a Page

I keep forgetting how to create a link to a part of a page using Textile Markup and have to look it up every time I need it. So, I’m putting this short post here so that I remember.


My blog is built using Jekyll and uses Textile Markup rather than Markdown (most of the time). I find that it gives me more control over the HTML that is generated (also, I have more experience with it and old habits die hard).

One of the things that is useful on an HTML page is to be able to link to a section on the page directly so that you don’t have to tell readers something like “Scroll down that page till you find the section called Design and then you can read it from there”. HTML provides this ability as part of the href attribute and fragment URLs. In brief, this is when your URL has a fragment after the path to the page, starting with a #. For example, the link above is: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-href (you can see the link to the section #attr-href at the end of that URL).

Adding it in Textile

So, we know how to access it – we just need to ensure that the browser knows how to find where that anchor is. That’s where we need to make sure that our Textile markup includes the anchor. If you look at any “reference online on how to jump to a specific part of an HTML page”:“https://www.w3docs.com/snippets/html/how-to-create-an-anchor-link-to-jump-to-a-specific-part-of-a-page.html”, the way you do this is to ensure that the paragraph or element that you want to jump to has an HTML ID. For Textile, this is as explained on Class and ID attributes on the Textile site by doing something like:

p(#my-paragraph). This is a paragraph that has an @id@.
h2(#next-one). Another one but this time a Heading 2
p(my-class#next-one). A paragraph of the HTML class @my-class@ and with @next-one@ as the ID.

So, that’s all we need to know: if you only need an anchor, put a #id-name within parentheses after the heading or the paragraph marker. Just ensure that the IDs you use are unique!

Finally, a quick note on how to link to a fragment on the same page using Textile. Clicking on this link takes you back to the Background section on top. The way to do this is just the # anchor as the link. So, the above link is created using <notextile>"link text":#background</notextile> which just attaches to the page URL. You can use this ability to manually create a Table of Contents of “on this page…” like below:

As with a number of notes on this site, this post is written only so that I can remember this! It’s great if you find it useful.

comments powered by Disqus