Support relative links with both markdown as well as jekyll about pages-gem HOT 20 CLOSED

I think this is fixed with #360 ?

from pages-gem.

I've just hit this bug/limitation. Where in the GitHub pages / Jekyll stack could we modify the markdown to html conversion to (optionally) rewrite these local links from architecture.md to architecture.html? i.e. Is this repository the correct place to file an enhancement request, or is it elsewhere?

from pages-gem.

Here's a hack to get around it:

Add this to the bottom of the page/layout file (after any content for which you want relative links to work):

<script language="javascript">
var x = document.links.length;
for (i = 0; i < x; i++) {
  var thisHREF = document.links[i].href;
  if (thisHREF.indexOf(window.location.hostname) > -1) thisHREF = thisHREF.replace(".md","/").replace("/index/","/");
  document.links[i].setAttribute('href', thisHREF);
}
</script>

That basically "pretties up" relative links when rendered on your GitHub Pages site, but leaves the .md path in the HREF source, so that the link will work in GitHub's viewer. Until there's a real solution, it's at least something.

from pages-gem.

@benbalter doesn't your pull request #360 close this?

from pages-gem.

@stefanseefeld I know this is an way old issue, but could you give an example of what is not working for you and what you'd like it to do?

from pages-gem.

On 05/01/15 12:31 PM, Mads Ohm Larsen wrote:

@stefanseefeld https://github.com/stefanseefeld I know this is an
way old issue, but could you give an example of what is not working
for you and what you'd like it to do?

Sure:

In my master branch I have a "doc/" subdirectory containing markdown
files that use relative links to refer to each other, so I can navigate
these docs on github (example:
https://github.com/openvsip/openvsip/blob/master/doc/getting-started.md,
notably the "Architecture" link at the very bottom)

I would like to be able to process these files verbatim by jekyll to
generate the project's website (http://openvsip.org/). However, the
links wouldn't work, as they are referring to ".md" files, while they
now need to refer to ".html" files. It would be great to have a notation
that abstracts the specific file reference into a medium-agnostic link
that works verbatim in both cases above. (Python's Sphinx uses a link
grammar that supports medium-agnostic cross-references, so what I'm
asking for isn't an entirely new concept. FWIW.)

Thanks,
Stefan

  ...ich hab' noch einen Koffer in Berlin...

from pages-gem.

Of course, relative links aren't the only thing that needs to change. At the very least, you would need to add YAML front matter to each file so that it is rendered by Jekyll.

A related but likely out-of-scope issue is that ideally I would like for my website (which uses a gh-pages branch of my repo) to pull the markdown out of the master branch automatically, so the website gets updated automatically whenever I add to my documentation on the master branch.

This is most definitely outside the scope of Jekyll, but a very cool idea!

from pages-gem.

Maybe through permalinks and folders you could get the desired structure?

For example if you have the architecture.md

put it in /architecture and rename it readme.md
then put a permalink in the YAML front matter to /architecture/

Seems like a cumbersome solution and not sure if it will achieve the result you are looking for, but I thought I'd toss it out there.

then the links can point to /architecture/ and it will render on GIthub in markdown and through jekyll in HTML

from pages-gem.

I found a solution if the files are in the root directory but I don't like it because

1. It feels like a hack
2. I don't know if it has SEO problems.
3. Doesn't seem to work locally (which is why I'm posting here)

The solution is in this SO answer starting at the part that begins with "Relative linking to these documents works if you include the following jQuery function..."
http://stackoverflow.com/a/16389663/142358

Basically @CoryG89's interesting solution runs some javascript when the page loads to change links from .md files to pretty URLs. So if you create a relative link that works on github like [test](test.md) then the above changes
http://www.example.com/test.md
to
http://www.example.com/test

However when I try this locally the http://www.example.com/test link is broken/returns 404 and only http://www.example.com/test.html is served.

Anyone know why this works on Github but not locally? I'm using the latest pages gem.

from pages-gem.

Steve,

thanks for continuing to think about possible solutions.

I believe a true solution has to establish some actual markup for link
targets that are neither external URLs nor filenames, but rather
abstract entities that map to files in any given medium.
It seems supporting this may not even require any user-visible
(syntactic) changes, just an extension of how the parser handles links.
(It could try to interpret a link target as a file, and only if that
doesn't exist fall back to handling it as an abstract entity requiring
some pre-established mapping...
Oh, and jekyll would of course need to translate these link targets to
explicit references to html files.

    Stefan

  ...ich hab' noch einen Koffer in Berlin...

from pages-gem.

I think the best way to write this would be a plugin: http://jekyllrb.com/docs/plugins/

from pages-gem.

@davidsilvasmith And then ask GitHub nicely to whitelist the plugin? https://help.github.com/articles/using-jekyll-plugins-with-github-pages/

from pages-gem.

If you want to have it on github pages then I recommend using folders and readme.md

in readme.md make a permalink in the front matter.
for example make a /help/section1/readme.md

That link will resolve in github. Then to make it resolve in jekyll add a permalink to the readme.md frontmatter like this:

---
permalink: /help/section1/
---

Then your links can be /help/section1/ and they will work in both Github and HTML.

Does that work for you?

from pages-gem.

@davidsilvasmith if I understand your method correctly this only works with readme files and one link per file/folder since linking to a folder on GitHub shows its readme file. IMHO it is a creative solution but a little too limiting and the solution presented here is better even if it is more complicated. http://stackoverflow.com/a/16389663/142358

from pages-gem.

@stevemoser yes seems like you have a good handle on the problem and existing solutions.

from pages-gem.

i've written a simple plugin to solve this. put this in _plugins/, and make links refer to the *.md files (so github rendering linking works); if you build it with jekyll (when you are able to run plugins) the links are changed to *.html. since github doesn't run plugins, this isn't applied.

module ChangeLocalMdLinksToHtml
  class Generator < Jekyll::Generator
    def generate(site)
      site.pages.each { |p| rewrite_links(site, p) }
    end
    def rewrite_links(site, page)
      page.content = page.content.gsub(/(\[[^\]]*\]\([^:\)]*)\.md\)/, '\1.html)')
    end
  end
end

it's not perfect (i'm sure you could fool the regex) but it has been good enough for my purpose.

from pages-gem.

I recommend this issue be renamed Support navigable source. I am very happy that despite being so old, it has not been closed as “Won’t Fix”. It is currently the oldest open issue by far.

When people are collaborating on a website or documentation, it is very useful to be able to navigate the unpublished source, especially when pending changes span multiple pages or include links to new pages. GitHub explicitly added support for this in Jan 2013. “GitHub will automatically transform your relative links based on whatever branch you're currently on, so that the link always works,” allowing contributors to view different versions and branches of an interlinked set of pages. The request for this feature on Stack Overflow and the announcement of GitHub's resolution are very popular.

The superb Markdown editor Editorial supports this, so I can navigate my website or documentation source in my local clone of my repo, or source that isn’t in Git or GitHub at all.

To support contribution to websites or documentation by people that aren’t technical, I strongly recommend that this be seamless and magical. Users compose their website or documentation source using working relative links, and Jekyll (either natively or via a plugin supported by GitHub Pages) magically makes those links continue to work in the rendered static pages. It makes sense for this to be default behavior, though if there is a risk that existing sites would break, an explicit Jekyll config switch or enabling of a plugin is fine.

If I were a Ruby coder, I'd gladly do the work for this.

The issue number, #69, is a very apropos! It’s all about making sure both partners, the markdown source and the Jekyll generated static html, get satisfaction, that neither is left hanging. Reciprocal love baby! :)

from pages-gem.

So, the way I go about this without plugins is when I synchronise from master to gh-pages, I run a makefile to pull the source (as in documentation source) into the pages tree.

While pulling the contents of the documents I run sed to replace any relative urls with a macro that resolves relative file paths into permalinks.

// makefile
DOC := $(shell git ls-tree -r --name-only master | grep '.md')

sync: $(DOC)

%.md:
    echo --- > $@
    echo --- > $@
    git show master:$@ | \
        sed -E 's/(\[.*\])\(([^:]*)\)/\1({% include path_url path="\2" %})/g' >> $@

The path_url macro is just a simple lookup in site.pages, we can resolve the urls because jekyll sets the original path by default on all pages.

// _template/path_url
{% assign path = page.path | append: include.path %}
{{ site.pages | where: "path", path | map: 'url' }}

from pages-gem.

We're hitting the same problem: we have documentation in GitHub that is also transformed into a hosted site via Jekyll.

Am I understanding the correct workaround here? If I have this kind of structure:

docs/README.md "See details in [Foo](foo.md) and [Bar](bar.md)."
docs/foo.md "Details about foo..."
docs/bar.md "Details about bar..."

then the recommended workaround is

docs/README.md "See details in [Foo](foo/) and [Bar](bar/)."
docs/foo/README.md "Details about foo..."
docs/bar/README.md "Details about bar..."

Is that correct, more or less?

from pages-gem.

I think the problem is that GitHub wants .md links and Jekyll wants .html:

#69

But I'm not sure how to fix this yet. One option might be changing our naming scheme from requiring Page.html names to pointing to directories

E.g.:

This:

https://github.com/trustedci/OSCTP/blob/master/assets/Documentation.html

To this

https://github.com/trustedci/OSCTP/blob/master/assets/Documentation/

from pages-gem.