Fix links in docs to work while browsing on GitHub and on hubot.github.com

[technicalpickles]

It happened quietly, but the docs/ directory is now used to power hubot.github.com. Part of that was changing links to point to like /docs/scripting/ instead of docs/scripting.md. On the downside, we now have broken links if you browse https://github.com/github/hubot/tree/master/docs . We can make sure the links all work inconsistently, but the documentation has lived in the repository for so long, people link to them directly.

Since then, we've had a ton of PRs to fix the link the link, and I have to explain why this is. I expect to see more of them 😓

So, let's figure out a way to make them work in both. This is complicated by hubot.github.com being a separate private repo for historical reasons.

cc @jglovier @gjtorikian @parkr @benbalter since we've talked about this at one point or another

[gjtorikian]

I can't imagine any clean workaround for this. In hubot.github.com, we have script/bootstrap call git submodule update --init --recursive. As part of that bootstrap process, we could rewrite links in the submodule that match the GitHub format into a path for Jekyll. We could then add ignore = dirty to ignore these changes in the submodule.

That's all I got. 😞 Maybe we can/should also import the content (sans history) into gh-pages instead of keeping it separate.

[technicalpickles]

Could we make the permalinks have a .md? That is, /docs/scripting.md instead of /docs/scripting/index.html like it is now. I wonder if that would be correctly served up as html or not once generated...

Or maybe /docs/scripting.md/index.html. That way, links to /docs/scripting.md would work, albeit with a redirect in there.

[jglovier]

Could we make the permalinks have a .md

I don't think that will work. Since those links are just href attributes in the HTML, Jekyll doesn't know to convert them to anything.

Or maybe /docs/scripting.md/index.html

That one I have no idea if it will work, although I'm not sure why it even would?

[technicalpickles]

Or maybe /docs/scripting.md/index.html

Surprisingly, it totally does. At least, in development it works.

[technicalpickles]

Could really use some help on this. Seems like we get a PR to 'fix' individual pages every few days, and it's really annoying to close them without a path to resolution.

[parkr]

I'd suggest linking to them externally and having a single source of truth. Perhaps providing redirect pages for the old links that don't work? Trying to browse a Jekyll site (with valid links) on both GitHub and the rendered site doesn't make sense. If just the source was sufficient, you probably wouldn't have chosen to use Jekyll. 😃

Do you have a CONTRIBUTING.md? Maybe if that contained instructions? Unfortunately, it's not that easy if people expect internal and external links to work like a charm. Here, it's all about managing expectations.

[benbalter]

and having a single source of truth

What's the value of equally supporting the ability to browse the docs via GitHub and via the documentation site? Sounds like a lot of headache, and suspect the branded pages version could be of more value to end users? Curious your reasoning here.

[gjtorikian]

What's the value of equally supporting the ability to browse the docs via GitHub and via the documentation site?

@technicalpickles talked about this briefly in the original write-up:

We can make sure the links all work inconsistently, but the documentation has lived in the repository for so long, people link to them directly.

It's also better to provide the reading experience which the user feels most comfortable with. I personally do not find it problematic to support both systems. We have a plan in place, at least, to achieve the goal already.