search

davideuler / gitblit

Automatically exported from code.google.com/p/gitblit
Apache License 2.0
0 stars 0 forks source link

Enable relative linking from one Markdown document to another #324

Closed GoogleCodeExporter closed 9 years ago

GoogleCodeExporter commented 9 years ago 
For documentation purposes, I want to add several markdown files to my 
repository.   I find that if I put them all in the repo's root directory, then 
I can link between them with no problems:

/README.md  -- page with links to analysis.md
/analysis.md

with links that look like:

[Link 1](http://localhost:8080/blob/test.git/HEAD/analysis.md)
or
[Link 2](/blob/test.git/HEAD/analysis.md)

This works fine.   However, if I want to group the documentation into a 
subdirectory 'doc':

/README.md
/doc/analysis.md

.. then I can't get any of the following links to work:

[Link 1](doc/analysis.md)
[Link 2](http://localhost:8080/blob/test.git/HEAD/doc/analysis.md)
[Link 3](/blob/test.git/HEAD/doc/analysis.md)
[Link 4](/blob/test.git/doc/HEAD/analysis.md)

(Obviously one workaround is to only link to markdown files in the root 
directory, but that's a shame from the perspective of keeping things tidy)

I've reproduced this behaviour using GitBlit 1.3.2 on both Windows XP and Linux.

See forum post: https://groups.google.com/forum/#!topic/gitblit/bkVY4gaHv28

Original issue reported on code.google.com by duncan.j...@gmail.com on 15 Oct 2013 at 12:27

GoogleCodeExporter commented 9 years ago 
I was just about to attempt this as well. I would definitely be keen on being 
able to create a main readme that is simply a tree of docs that point to other 
.md files.

Original comment by ch...@futurestatemobile.com on 20 Oct 2013 at 10:18

GoogleCodeExporter commented 9 years ago 
A few days ago I switched the Markdown parser to pegdown which I expect to give 
more freedom during html generation which should help with this feature request.

Gitblit does have an existing feature to list all Markdown files in a repo, 
just like an index, but I agree that relative linking of documents (and 
resources) would be a really nice improvement.  I suspect the "relative" aspect 
of this will require "relative to the repository root", not necessarily 
relative to the document, like normal html.

If someone wants to take a stab at implementing this, that would be fine by me. 
 A few thinks to consider:
1. mounted vs. unmounted parameters
2. consider hijacking the pegdown [[Wiki-style links]] Wiki link formatting for 
relative Markdown links?
3. Implement image links using the raw url

Original comment by James.Mo...@gmail.com on 20 Oct 2013 at 11:33

GoogleCodeExporter commented 9 years ago 
This is implemented and pushed to master.  The implementation works with all 
Gitblit's link generation quirks and uses the [[WikiLinks]] syntax.

Rules:

1. Only the [[link]] syntax is supported.
2. Links are specified relative to the root of the repository 
[[wiki/intro/features]]
3. Only the document path segment is displayed as the link text 
[[wiki/intro/features.md]] = <a>features</a>
4. Extensions are optional.  If an extension is unspecified, Gitblit will test 
for all known permutations of the filename when rendering.
5. Spaces in the link are replaced with '-'.  This applies to the entire link.  
Spaces in a directory name are a really bad idea anyway.

As a bonus, if Gitblit finds a "home" Markdown file (of any registered 
extension) it will display this document in a "home" tab on the Docs page.  The 
document list will then be displayed on a "pages" tab.  This is similar in 
appearance to Github's Wiki function.  If the "home" file is not found, the 
document list is displayed just like it does in <= 1.3.x.

Original comment by James.Mo...@gmail.com on 25 Oct 2013 at 1:25

GoogleCodeExporter commented 9 years ago 
Currently Pegdown does not support manipulation of the img tag generation like 
it does the anchor tag generation.  I have implemented this and opened a pull 
request[1] that enhances the Pegdown api for this use case.  Hopefully it gets 
merged and released to Maven Central in a timely fashion.

Once that happens, Gitblit can be enhanced to serve image links in a Markdown 
document directly from the repository.  I have preliminary code that does this 
very thing and it works great.  :)

[1]: https://github.com/sirthias/pegdown/pull/115

Original comment by James.Mo...@gmail.com on 25 Oct 2013 at 6:35

GoogleCodeExporter commented 9 years ago 
I have updated the "next" site with the current code and created a home.md file 
to demonstrate the custom indexing.

https://next-gitblit.rhcloud.com/docs/gitblit.git
https://next-gitblit.rhcloud.com/raw/gitblit.git/master/HOME.md

Original comment by James.Mo...@gmail.com on 25 Oct 2013 at 11:14

GoogleCodeExporter commented 9 years ago 
Thanks James, I really appreciate the work you've done and look forward to the 
next release. :)

Original comment by duncan.j...@gmail.com on 28 Oct 2013 at 2:27

GoogleCodeExporter commented 9 years ago 
I've made some further changes here.

I decided that forcing repo-root relative-linking was dumb as I could determine 
the current context.  So now a link like [[mydoc.md]] is relative to the 
document and [[/mydoc.md]] is relative to the repository root which maps better 
to standard http processing.  Same for image links... which I'm still working 
on getting accepted upstream.

Additionally, the docs page is going to become compulsory (i.e. automatic) and 
there will be a new setting to specify root document tabs.

web.documents = home index readme changelog contributing license

If any matching files are found in the repo root and they are extension-less, 
txt/TXT, or their extension matches a registered markup extension - the 
document is rendered as a tab.

As part of this there are several more markup formats now rendered because I 
have integrated (older) Eclipse WikiText libraries: confluence, mediawiki, 
textile, tracwiki, twiki.

AsciiDoc is (working) possibility - but it doubles my library footprint 
(25MB->50MB) because it bundles JRuby.  I haven't decided if that is a good 
idea or not.  It's a nice, rich format and it is in-use on Github and the Git 
documentation is written in it.... but +25MB is expensive.

Demo of doc tabs here:

https://next-gitblit.rhcloud.com/docs/mirrors!butterknife.git

This particular page will also demonstrate repo-loaded image links, once my 
patch is accepted upstream.

Original comment by James.Mo...@gmail.com on 14 Nov 2013 at 6:30

GoogleCodeExporter commented 9 years ago 
Pegdown updated to 1.4.2. Image loading directly from the repository is now 
working.
Example here: https://next-gitblit.rhcloud.com/docs/mirrors!butterknife.git

Original comment by James.Mo...@gmail.com on 12 Dec 2013 at 4:18

GoogleCodeExporter commented 9 years ago 
1.4.0 released.

Original comment by James.Mo...@gmail.com on 9 Mar 2014 at 6:06

GoogleCodeExporter commented 9 years ago 
Hey, is it possible to add support for giving names to linked wiki pages?

I would like to name this kind of link: [[wiki/example.md]]

Original comment by basti...@gmail.com on 17 Feb 2015 at 7:52

GoogleCodeExporter commented 9 years ago 
It's possible, but I probably won't hack it in.

Original comment by James.Mo...@gmail.com on 18 Feb 2015 at 4:44

GoogleCodeExporter commented 9 years ago 
please add label support for relative links

Original comment by icks...@googlemail.com on 31 Mar 2015 at 11:14