Render a link to source repo

[paul121]

Currently farmOS.js / farmOS.py and even farmOS don't have a link back to their respective github repos. They could add it themselves, but perhaps it would be better to add a nice little Github icon + link in this repo itself. Ideally we could pull the url from the source repo config?

[jgaehring]

Yes! Great idea!

They could add it themselves, but perhaps it would be better to add a nice little Github icon + link in this repo itself.

Totally. 💯 I really don't think it belongs in the source repos. If nothing else it's totally unnecessary if someone is already viewing the content in GitHub. Also, what if the repository is cloned to GitLab, or some private git server? What if someone forks the repo and wants to host the docs on a different website, with different links to that fork? Links like ought to be the responsibility of the publisher, imo.

Ideally we could pull the url from the source repo config?

Yep! Should be pretty straightforward. When referencing that configuration, I've actually opted to store it all as JSON in the .cache directory, rather than adding it to GraphQL (TL;DR: GraphQL doesn't handle unstructured JSON well and is a PITA if you don't know the exact shape of the JSON at build time). So it can be imported dynamically in the layout:

https://github.com/farmOS/farmos.org-EXPERIMENTAL/blob/761336fecf7fc2335bc6cc070c944fcc6bc72123/src/components/layout.js#L99

Hardcoding that file path isn't quite ideal, cuz I don't know if I'll need to change it in the future, but our current Webpack/Gatsby version only supports "static specifiers" for dynamic imports (ie, an actual string as the argument, not a template literal or variable). In the meantime, we can try to limit how often that's used, and if we need it in other components, we can just pass it down as props.

[jgaehring]

Just posted this in #24:

All this makes me think this logic should be written into the NestedNav component itself, or as a special ExternalLink component or something, since seems more and more like a concern for the rendering layer.

@paul121, this may mean we don't need #22 for the links to the source repos themselves, but I would still like to use what you've done there for adding the "Edit this page on GitHub" button.

I'm also backtracking a little on my earlier comment above:

I really don't think it belongs in the source repos.

I still don't think it is good to include links like that in the Markdown, but I think it makes perfect sense in the config.yml file, since that's already kinda opinionated about how the pages will be rendered (ie, using MkDocs or the farmOS Gatsby site). And putting it there would reduce a lot of complexity from of this.

So for the farmOS.js config.yml, it would just look like this:

nav:
  - Getting started: index.md
  - Schemata: schemata.md
  - Remotes: remotes.md
  - Entities: entities.md
  - Metadata: metadata.md
  - API reference: api.md
  - Source: https://github.com/farmOS/farmOS.js

Then something like the ExternalLink component I mention in #24 could handle all the rest, like adding the "open-in-new" and GitHub icon. Or we could use something like the MkDocs repo_url property, instead of putting in the nav, and then the Gatsby repo could figure out whether to render it or where, though I'm more inclined to using nav, personally.

What do you think?

[mstenta]

Not the final solution, but a first step PR: #63