Page MenuHomePhabricator

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

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

Details

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
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

Fabien requested review of this revision.Sep 14 2020, 19:18
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
_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.

This revision is now accepted and ready to land.Sep 15 2020, 17:08