I just wrote var api = new API({ description: [ // ... 'The task definition in the a is used as a JSON-e template. See', 'https://docs.taskcluster.net/reference/core/taskcluster-hooks/docs/firing-hooks', 'for more information.', but that link is absolute. We will need a way to make such links relative -- probably by doing some kind of string substitution on the documentation when publishing it, e.g., '{{docs-root}}/reference/core/taskcluster-hooks/docs/firing-hooks',

We may need this within the docs site, too. There are lots of instances of [..](/manual/foo/bar) but that won't work if https://docs.taskclsuter.net/ moves to https://taskcluster.net/docs.

I've been thinking about this a bit. Could we come up with some URL pattern that would sort-of work in raw Markdown, but which we could easily translate using a rootUrl? Perhaps that just means https://links.taskcluster.net, and we can put some helpful redirects on that site? So if a library's README points to the scope docs, for example, clicking the link in Github would take you to https://links.taskcluster.net/docs/manual/design/apis/hawk/scopes which would redirect to TC's production instance. But, clicking that link in the docs for https://taskcluster.mysite.com would go to https://taskcluster.mysite.com/docs/manual/design/apis/hawk/scopes and get you precisely the scopes for that instance. So basically we'd translate rootUrl=https://links.taskcluster.net to rootUrl=$TASKCLUSTER_ROOT_URL at deploy time.

Once bug 1466604 lands, everything is at /docs on both the old (https://docs.taskcluster.net) and new (rootUrl) sites. So relative URLs that start with /docs will work for things like the API description in comment 0. I would like to try to simplify the reference docs a bit, and I think the way to do that is: - don't read READMEs anymore (they often contain instructions for testing, etc., which aren't a good fit for the docs site) - serve a repo's docs/ directory verbatim at /docs/reference/<tier>/<service>/docs, including the `.md` suffixes - redirect from /docs/reference/<tier>/<service> and /docs/reference/<tier>/<service>/docs to /docs/reference/<tier>/<service>/docs/index.md, if that file exists - represent `index.md` in the table of contents on the side as a link on the parent, and continue to elide the /docs/ path component in the table of contents Then that docs directory is self-contained, and a link like [task life cycle](task-life-cycle.md) will work both in github and in the docs site. The last part means (ignoring (api|events) which will not change): taskcluster-foo - /docs/reference/<tier>/taskcluster-foo/docs/index.md Task Life Cycle - /docs/reference/<tier>/taskcluster-foo/docs/task-life-cycle.md Thingies - /docs/reference/<tier>/taskcluster-foo/docs/thingies/index.md Thing1 - /docs/reference/<tier>/taskcluster-foo/docs/thingies/thing1.md Thing2 - /docs/reference/<tier>/taskcluster-foo/docs/thingies/thing2.md /docs/reference/<tier>/taskcluster-foo redirects to /docs/reference/<tier>/taskcluster-foo/docs/index.md /docs/reference/<tier>/taskcluster-foo/docs redirects to /docs/reference/<tier>/taskcluster-foo/docs/index.md /docs/reference/<tier>/taskcluster-foo/docs/thingies redirects to /docs/reference/<tier>/taskcluster-foo/docs/thingies/index.md

(the reason that fits under this bug is that it makes it easier to test relative URLs in the github view)

I just checked in with Eli (since he has in mind the future of the `taskcluster.net` domain), and I think we can also keep https://docs.taskcluster.net/docs links in READMEs and various other documents likely to be accessed outside of the docs site itself. For the moment, that points to the https://taskcluster.net instance. When we shift to a homepage, we will want to figure out some way to have "generic" documentation, and we can either host that at https://docs.taskcluster.net or redirect from there to wherever we decide to host it. All of which is great, because it means we don't have to work too hard to eliminate references to docs.taskcluster.net anywhere.

I think this is going to be a good thing to have, but not for a while. Docs more-or-less work now. Comment 14 would be great, as would getting rid of <tier>/ completely. But all of that will be a lot easier when this isn't a hacked-together pile of gulp.