Apiary Blueprint Docs: Unable to create clickable links between sections

[foxx]

If I try and link to another section in the blueprint, it doesn't actually work. Upon checking the source code, I cannot see any <a> tags on the titles themselves, and clicking on the links results in a redirection to a broken page. It would be nice if we had the ability to link to sections.

Example

## Passwords

Some extra info about passwords

## Register user [PUT /users]

For more info about passwords, see [Passwords](#Passwords)

[zdne]

I wonder if this is related to https://github.com/apiaryio/api-blueprint/issues/212 ? note there is also a bug in parser that prohibits markdown reference-style links as documented here https://github.com/apiaryio/snowcrash/issues/55

[pksunkara]

I don't think apiaryio/snowcrash#55 have any bearing on this since the rendering in Apiary.io is done by robotskirt. I guess the problem here is that #Passwords will not be a valid link in Apiary documentation since Apiary has it's own reference links. We should explore and see what exactly the issue is.

[zdne]

Oh you are correct @pksunkara . I do not think an anchor for #Passwords (e.g <a name="Password">) is defined in the document. Please use full permalinks as generated by Apiary. e.g. http://docs.apiblueprintapi.apiary.io/#reference/api/service-root

[zdne]

So in your case #reference/Passwords could work.

[pksunkara]

@zdne That would work for Apiary documentation. But API Blueprint is also a markdown file where the #reference/Passwords would not work.

[zdne]

But API Blueprint is also a markdown file

I am afraid the least common denominator is HTML's <a name= since Markdown as such does not have any "standard" way of doing this and different vendors do this differently.