CODEWITHSUNDEEP
markdownwikigithub-flavored-markdownasciidocwiki-markup
Krazy Glew
Krazy Glew

Reputation: 7534

Compact wiki-like link syntax in Asciidoc and Markdown, like [[page-name]]?

Q: is there a compact link syntax in asciidoc? Like [[page name]], where the link target is derived from the link text?

---+ DETAIL

Most wikis have a very easy, compact, syntax for links to different pages in the same wiki.

E.g. the original WikiWikiWeb used CamelCase - words that were CamelCase were automatically links.

E.g. many wikis adopted a syntax like double square brackets to identify a [[link to a page]]. Typically the actual target page name is derived from the link text by transformations such as changing spaces to _underscore or -dash or +plus sign, or full URI-encoding.

The wikis associated with Github project repos support the double square bracket syntax - with the extra feature of searching along a sequence of file suffixes, .md/markdown, .asciidoc/:-), etc., allowing the same wiki to contain pages written in different markups. For all of the markup varaints supported, except asciidoc - which already uses double square brackets for link targets or anchors.

Unfortunately AFAICT the semi-formal GitHub Flavored Markdown docs like https://github.github.com/gfm/#links do not describe this compact double bracket syntax and perhaps as a consequence neither does the GFM to asciidoc conversion tool kramdoc.

Q: is there a compact link syntax in asciidoc?

AFAIK, AsciiDoc links must specify both link text and target, with the most compact form being the relative link link:Page-Name.html[Page-Name]. This is redundant, if the link text and the page basename are the same.

(Except, asciidoc makes link text and target the same if it looks like a link: https://asciidoctor.org.)

For that matter, is there an official compact link syntax in Markdown, that kramdown/kramdoc understand? Or is that lack the reason why the GitHub wiki supports double square bracket [[page name]]?

---+ PONTIFICATING

IMHO the most important features of wikis are

i.e. links that are easy to write, easy to discover, and easy to create.

I would be very disappointed if official Markdown and AsciiDoc do not support such compact links. especially since I am being forced to use AsciiDoc at work.

AFAICT AsciiDoc supports compact <<intra-document>> links or cross references, often with the target anchors created implicitly from section title text. But AFAICT links between different wiki pages or documents are forced to be much more verbose.

For that matter, I also complain that on the GitHub wiki, in a .asciidoc wiki page, links to pages that do not exist yet are not distinguished from pages that already exist.

Upvotes: 1

Views: 698

Answers (1)

John Schmitt
John Schmitt

Reputation: 1218

Yes. I learned about in this discussion on the vviki project. See this summary, here is an excerpt:

xref:foo[Foo]             - a link to a location in the same document with ID "foo"
xref:bar#[Bar]            - a link to a document named "bar"
xref:bar.adoc[Bar]        - same
xref:bar.adoc#[Bar]       - same
xref:bar#foo[Foobar]      - a link to location ID "foo" in document "bar"
xref:bar.adoc#foo[Foobar] - same

Upvotes: 2

Related Questions