[WEBSITE] Pull all markdown docs from ABC and render them
ClosedPublic
Actions

Authored by Fabien on Sep 14 2020, 19:18.

Details

Reviewers

jasonbcox

Group Reviewers

Restricted Project

Commits

rABCWEBd6328a9f1621: [WEBSITE] Pull all markdown docs from ABC and render them

Summary

This diff extends the fetch-documentation.sh script to copy all the
markdown files from the ABC repository to the website repository in
order to be processed and rendered by Jekyll.

The files can be accessed as if navigating through the ABC repository,
by using the project root relative link to the URL and substituting the
.md extension for .html. Examples:
bitcoinabc.org/CONTRIBUTING.html, bitcoinabc.org/doc/build-unix.html

In order to keep the links working between the markdown files, a couple
plugins are added to Jekyll:

The jekyll-relative-links plugin will translate the relative .md links to their .html counterpart
A custom plugin will transpose to text the other relative links (such as source files) which cannot be rendered by Jekyll, and convert the project relative links (starting with a /) to file relative links so they are processed by jekyll-relative-links

The next step will be to replace the links to external markdown files
such as CONTRIBUTING.md and DISCLOSURE_POLICY.md with links to the local
pages.

Test Plan

make doc
make serve

Navigate through the pages (e.g.
http://127.0.0.1:4000/CONTRIBUTING.html) and check there is no dead
link.

Diff Detail

Repository

rABCWEB Bitcoin ABC Website

Branch

pull_doc

Lint

No Lint Coverage

Unit

No Test Coverage

Build Status

Buildable 12736
Build 25555: arc lint + arc unit

Event Timeline

Fabien created this revision.Sep 14 2020, 19:18

Herald added a reviewer: Restricted Project. · View Herald TranscriptSep 14 2020, 19:18

Harbormaster completed remote builds in B12722: Diff 23477.Sep 14 2020, 19:18

Fabien requested review of this revision.Sep 14 2020, 19:18

Fabien added a child revision: D7438: [WEBSITE] Use local links for CONTRIBUTING and DISCLOSURE_POLICY.Sep 14 2020, 19:20

jasonbcox requested changes to this revision.Sep 14 2020, 21:38

jasonbcox added a subscriber: jasonbcox.

jasonbcox added inline comments.

_plugins/markdown-override-broken-links.rb
6 ↗	(On Diff #23477)	MarkdownOverrideBrokenLinks?
13 ↗	(On Diff #23477)	Is this necessary?
68 ↗	(On Diff #23477)	This will be easy to ignore if it's not formatted as a warning (colored, maybe bold?, etc.)
93 ↗	(On Diff #23477)	Maybe rename this to something like `is_lone_anchor` because it does not match on self-referential anchors, which was not expected when I read it. But seeing how this function is used, it's not actually an implementation issue.
scripts/fetch_documentation.sh
186 ↗	(On Diff #23477)	The permalink shouldn't be from the top level or any markdown file could collide with existing pages. `/doc/` or similar may be appropriate.

This revision now requires changes to proceed.Sep 14 2020, 21:38

jasonbcox mentioned this in D7438: [WEBSITE] Use local links for CONTRIBUTING and DISCLOSURE_POLICY.Sep 14 2020, 21:40

Fabien added inline comments.Sep 15 2020, 07:20

_plugins/markdown-override-broken-links.rb
68 ↗	(On Diff #23477)	It is not intended to be a warning, the link being broken is due to it being pulled from another repo (the link is valid in the context of the source repo). I should just remove the messages as they look confusing.
scripts/fetch_documentation.sh
186 ↗	(On Diff #23477)	The permalink actually follows the tree structure, so very little files will be on top level and are very unlikely to cause collisions. Changing the root actually won't prevent collision either and will make the URL more difficult to understand, so I prefer to leave it as is.