I suggest you ...

Support Intradocument links in markdown

It would be very convenient to have intra-document links in the blueprint.

The syntax {#Header} is sometimes used to add names to headers in the rendered html. Source: https://meta.stackexchange.com/questions/29063/why-is-a-special-character-in-markdown

Alternatively, please render a name, id, or href on headers from markdown.

As examples:

Bitbucket renders it as an id; `# Hello world` becoming `<h1 id="markdown-header-hello-world">`.

Github renders it as an href: `# Hello world` becoming `<h1 href="#hello-world">`

16 votes
Vote
Sign in
Check!
(thinking…)
Reset
or sign in with
  • facebook
  • google
    Password icon
    I agree to the terms of service
    Signed in as (Sign out)
    You have left! (?) (thinking…)
    KevinKevin shared this idea  ·   ·  Admin →

    10 comments

    Sign in
    Check!
    (thinking…)
    Reset
    or sign in with
    • facebook
    • google
      Password icon
      I agree to the terms of service
      Signed in as (Sign out)
      Submitting...
      • Lukas LinhartAdminLukas Linhart (Admin, apiary.io) commented  · 

        Vojtech: For example, this would link to "Create Step" action in my testing API: [create step](#reference/test-steps/test-steps/create)

      • GoodMichelleGoodMichelle commented  · 

        Back functionality works for me. Tested in Chrome, Safari and Firefox.

      • Lukas LinhartAdminLukas Linhart (Admin, apiary.io) commented  · 

        Hi Maxim,

        at least for me (Chromium), in the new documentation, if I click on resource group in TOC and then on the resource in TOC and hit back, I am navigated to the resource group heading as expected.

        Regards,

        Lukas

      • MaximMaxim commented  · 

        An even better experience would be a possibility to go back to the place where you klicked the permalink by simply hitting browser's back button.

        If I am not completely wrong, even with permalinked headers, hitting the back button after I navigated to a permalink, will not bring me back exactly to where I left off by clicking the permalink, but to the beginning of the chapter/header.

        If I want to reference a resource description in the introduction part of my documentation I currently consider opening it in a new tab by adding target="_blank" to the a-Tag.

      • Lukas LinhartAdminLukas Linhart (Admin, apiary.io) commented  · 

        Hi steve,

        yes, we are working on it.

        The new docs are already generating permalinks for resources and resource groups. We are now working on generating permalinks for the headers in the introduction section.

        Regards,

        Lukas

      • stevesteve commented  · 

        are there any plans to accomplish this?
        As Maxim commented, in the "old" docs, you render out <a name="myref"> so I can add inter document links - but under the "new" docs, there isnt any way to do that - its the only show stopper for us moving over to the new format (which is way nicer and in my view)

      • Lukas LinhartAdminLukas Linhart (Admin, apiary.io) commented  · 

        Hi Maxim,

        we are not actively trying to discontinue HTML support, but there are some major overhauls due regarding sanitisation and XSS prevention.

        Most of the things should continue to work, but I don't want to guarantee anything in case we'd have to close some security loopholes.

        As for the use-case, we will definitely support it and we'll let you know here once we have the "official" way we can guarantee.

        And yes, we realise it's fairly important for handling larger API descriptions.

        Regards,

        Lukas

      • MaximMaxim commented  · 

        Alternatively some people suggest using HTML a-Tags with name attribute and referencing them by i.e. [Reference](#myRef), which currently works in usual mode, but does not work properly in 'new documentation' mode. In this mode the navigation with back and forward button of a browser is not working correctly.

        But as I am not able to put an HTML-Tag in front of a new Group, I am only able to place such an id-anchor only after the rendered H1-Tag which is very pity.

        Additionaly i have read that you probably will discontinue to support html tags in markup at all. Is that true?

      Feedback and Knowledge Base