Markdown conversion from wiki to documentation break links

[ErwanLeroux]

Hello,

I think there is something wrong in the html version of doc/Home.md

First link Welcome to the <a href="https://github.com/shaarli/Shaarli/">Shaarli</a> wiki<embed src=".html" /> Notice the <embed> part

Second link For general info, read the <a href="https://github.com/shaarli/Shaarli/blob/master/README.md">README</a>.<a href=".html"></a> Notice the second <a>

There is more wrong links in the page, I will not list all of them because I think they all have the same cause. In doc/Home.md, I see this "[](.html)", which look like a typo.

Edit to show the link using proper Markdown syntax

[alexisju]

Wich version of shaarli is concerned / do you use?

The demo instance doesn't have this issue : http://shaarlidemo.tuxfamily.org/Shaarli/doc/Home.html

[ErwanLeroux]

I use the stable version.

[alexisju]

Do you have a link to you doc?

[ErwanLeroux]

Here you go : http://shaarli.elendar.fr/doc/Home.html

[alexisju]

Indeed. I guess it is a little bug of the compiler from wiki to html...

[ErwanLeroux]

Not sure, I think there is something wrong directly in the .md.

What is the purpose of [](.html) ? It look like a incomplete link.

[alexisju]

I think the md is generated directly from the wiki https://github.com/shaarli/Shaarli/wiki This .md is not supposed to be edited manually.

[ErwanLeroux]

Okay I was thinking the other way around, ie that the .md was the source of the wiki ^^

[ErwanLeroux]

I clone the wiki and checked, no trace of [](.html) inside, so something happens when the wiki is duplicated in doc/

[ErwanLeroux]

I found other wrong links Inside Developpement.md <a href="(https://api.travis-ci.org/shaarli/Shaarli.svg)](https://travis-ci.org/shaarli/Shaarli).html"><img src="https://travis-ci.org/shaarli/Shaarli" alt="(https://api.travis-ci.org/shaarli/Shaarli.svg)" /></a> Inside Example-patch---add-new-via-field-for-links.md + echo '<description><![CDATA['.nl2br(keepMultipleSpaces(text2clickable(htmlspecialchars($link['description'])))).$via.$descriptionlink.'[></description>'."\n</item>\n";](></description>'."\n</item>\n";.html)

It look like a regex is messing around when transposing from Github to .md

Edit: the regex probably look like replace [[(.*)]] by [\1](\1.html)

[virtualtam]

Hi @ErwanLeroux!

Please keep in mind that the current format for the local documentation is more of a convenience hack than a proper support:

• there are some (known) shortcomings when converting GitHub-flavoured Markdown to HTML:
  • relative links;
  • static resource links (images);

• 312 has been raised to switch to a proper, more flexible documentation system (Sphinx), and either host it on ReadTheDocs, or as a github.io website.

Feel free to submit a PR if you find a simple fix for the documentation make targets though :)

[ErwanLeroux]

Thanks @virtualtam, I saw that part of the makefile earlier, but I did not understand all of it. The generation of the doc is make htmldoc right ? I'm going to poke around to see what I can do.

[virtualtam]

To elaborate a bit: we use Pandoc to generate HTML documentation from the GitHub wiki pages.

Here's what is done by each Makefile target:

• doc clones the Shaarli wiki repository
• htmlsidebar parse the GitHub _Sidebar to generate a standard Markdown-formatted sidebar, then generates the actual HTML sidebar with Pandoc
• htmlpages parses all wiki pages, removes Markdown pages titles, applies some regexes with awk to fix most links, then generates the final HTML pages, each with a custom title and the previously generated sidebar

The whole process is quite a succession of hacks, resulting in a local documentation that is browsable enough...

Broken links mostly come from the GitHub-flavoured Markdown syntax (especially handy shortcuts for relative links) not being fully supported by Pandoc. So there is a risk that when fixing parsing for some links, other will end up being broken :(

[ErwanLeroux]

Thanks for the details, I figured as much, although I can't claim I understand all of the command used :) I'm currently testing a php script to use the github api to convert from GFM to html.

[ErwanLeroux]

All wrongs come from the use of [[Unit tests]] syntax on the wiki. I'm trying more regex to take account of this syntax

[ArthurHoaro]

Maybe we can just don't use this syntax?

[ErwanLeroux]

It's a possibility. At least I would recommend to not use it on image. [[images/firefoxshare.png]] should be ![](/shaarli/Shaarli/wiki/images/images/firefoxshare.png)

Note for later: On the sidebar, [[Home]] should be translated to [Home](../Home) Reference : https://help.github.com/articles/adding-links-to-wikis/

[ArthurHoaro]

Didn't make any test, but also relevant.

[ErwanLeroux]

I just tested it a bit [plugins](Plugin-System) : https://github.com/shaarli/Shaarli/wiki/Shaarli-configuration/Plugin-System [plugins](Plugin-System.md) : https://github.com/shaarli/Shaarli/wiki/Shaarli-configuration/Plugin-System.md

It seems that [xx](xx) and [xx.md](xx.md) are considered differents pages.

[virtualtam]

Closed per #772, see also #312