This repository has been archived by the owner on Feb 18, 2024. It is now read-only.
Switch documentation to mkdocs-material and host using Netlify #898
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
14 tasks
eliperelman
approved these changes
May 23, 2018
docs/v7.md
Outdated
| @@ -0,0 +1,3 @@ | |||
| Placeholder page to work around mkdocs/material's lack of support for | |||
| external links in the sidebar. Requests for this page will be redirected | |||
| to the URL specified in netlify.yml. | |||
There was a problem hiding this comment.
s/netlify.yml/netlify.toml/
docs/v5.md
Outdated
| @@ -0,0 +1,3 @@ | |||
| Placeholder page to work around mkdocs/material's lack of support for | |||
| external links in the sidebar. Requests for this page will be redirected | |||
| to the URL specified in netlify.yml. | |||
There was a problem hiding this comment.
s/netlify.yml/netlify.toml/
docs/v6.md
Outdated
| @@ -0,0 +1,3 @@ | |||
| Placeholder page to work around mkdocs/material's lack of support for | |||
| external links in the sidebar. Requests for this page will be redirected | |||
| to the URL specified in netlify.yml. | |||
There was a problem hiding this comment.
s/netlify.yml/netlify.toml/
docs/v4.md
Outdated
| @@ -0,0 +1,3 @@ | |||
| Placeholder page to work around mkdocs/material's lack of support for | |||
| external links in the sidebar. Requests for this page will be redirected | |||
| to the URL specified in netlify.yml. | |||
There was a problem hiding this comment.
s/netlify.yml/netlify.toml/
mkdocs.yml
Outdated
| - style-minify: './packages/style-minify.md' | ||
| - stylelint: './packages/stylelint.md' | ||
| # External links aren't supported in the sidebar, so we link to a | ||
| # blank page that has a corresponding redirect in netlify.yml. |
There was a problem hiding this comment.
s/netlify.yml/netlify.toml/
|
I've updated the PR to:
|
After the recent Gitbook hosted beta bugs & lack of ability to customise, we're going to try using the static site generator mkdocs, along with the mkdocs-material theme: http://www.mkdocs.org/ https://squidfunk.github.io/mkdocs-material/ The site will be hosted by Netlify, with each version of the docs being built from the respective branch, and served on different subdomains. Notable changes with mkdocs-material compared to Gitbook: * Index pages must be named `index.md` not `README.md` * All pages are converted to pretty URLs. eg `api.md` becomes `/api/`, which makes the extra directory nesting for just one file (eg `api/index.md`) unnecessary. * External links are not supported in the sidebar, so placeholder pages have been added, for which there are redirects in netlify.yml. Other changes: * Some existing links have been fixed to reference the `.md` file rather than the resultant URL, since otherwise mkdocs doesn't realise it's an internal link and performs no validation. (Though all links under `packages/` have to stay as absolute links, since the READMEs need to work standalone when published to NPM.) * The duplicated content between `packages/*/README.md` and `docs/packages/*` has been resolved by making the latter symlink to the former. Fixes #271. Fixes #620. Fixes #60. Refs #892.
|
Now deployed at: |
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
After the recent Gitbook hosted beta bugs & lack of ability to customise, we're going to try using the static site generator mkdocs, along with the mkdocs-material theme:
http://www.mkdocs.org/
https://squidfunk.github.io/mkdocs-material/
The site will be hosted by Netlify, with each version of the docs being built from the respective branch, and served on different subdomains.
Notable changes with mkdocs-material compared to Gitbook:
index.mdnotREADME.mdapi.mdbecomes/api/, which makes the extra directory nesting for just one file (egapi/index.md) unnecessary.Other changes:
.mdfile rather than the resultant URL, since otherwise mkdocs doesn't realise it's an internal link and performs no validation. (Though all links underpackages/have to stay as absolute links, since the READMEs need to work standalone when published to NPM.)packages/*/README.mdanddocs/packages/*has been resolved by making the latter symlink to the former.Fixes #271.
Fixes #620.
Fixes #60.
Refs #892.