Remove mdbook, transition docs to Docusaurus #10806

rmshea · 2020-06-25T06:12:34Z

Problem

Gitbook, while it remains a formidable documentation rendering solution, has provided a myriad of issue for our purposes. We're moving back to Solana-hosted and controlled docs with a formal transition to Docusaurus, a React-based Markdown renderer with plenty of flexibility and functionality.

You can see the current Docusaurus implementation here.

Summary of Changes

Remove mdbook scripts and other infrastructure
Add Docusaurus implementation
Remove Gitbook-specific syntax

rmshea · 2020-06-27T04:29:41Z

@danpaul000 looks like we'll need to adjust the /docs build subsequence. Could use your help to wrap that up—let's sync up on Monday.

mvines · 2020-06-29T15:36:16Z

Docusaurus has no search feature? That's a bummer. I use that in gitbook all the time :-/

danpaul000 · 2020-06-29T16:47:05Z

Why did everything in docs/ move to docs/docs/?

mvines · 2020-06-29T16:50:40Z

How does the deployment work?

rmshea · 2020-06-29T17:35:39Z

@mvines Docusaurus does have search — we just have to deploy it first and then we can use https://docsearch.algolia.com/apply/

rmshea · 2020-06-29T17:37:33Z

@danpaul000 That's how Docusaurus structures their markdown compartmentalization. I can rename the internal folder to whatever you might want, e.g. src

rmshea · 2020-06-29T17:38:40Z

How does the deployment work?

We can either use GitHub Pages, Netlify, Vercel, or any other static site host. I've used Vercel for the beta.docs.solana.com deployment just for ease of use.

https://v2.docusaurus.io/docs/deployment

danpaul000 · 2020-06-29T17:45:00Z

@danpaul000 That's how Docusaurus structures their markdown compartmentalization. I can rename the internal folder to whatever you might want, e.g. src

Yeah, docs/src/ is preferable. That's where the files currently exist, and would massively reduce the number of touched files in this PR making it easier to focus on the deployment change.

mvines · 2020-06-29T17:51:21Z

Oh we're going to want to backport this to 1.2, heads up!

danpaul000 · 2020-06-29T17:53:58Z

Oh we're going to want to backport this to 1.2, heads up!

Can we wait on the backport to soak test master and whatever deployment changes? I really don't want to break the main docs branch, we are getting a lot of traffic there lately.

mvines · 2020-06-29T17:58:06Z

Oh we're going to want to backport this to 1.2, heads up!

Can we wait on the backport to soak test master and whatever deployment changes? I really don't want to break the main docs branch, we are getting a lot of traffic there lately.

💯

mvines

I'll review again once docs/src is restored, too much churn here otherwise

Pull request has been modified.

garious · 2020-06-30T17:49:21Z

@rmshea, Rebase?

garious · 2020-06-30T17:49:36Z

@danpaul000, are you working on CI changes for this?

danpaul000 · 2020-06-30T17:50:31Z

@danpaul000, are you working on CI changes for this?

yeah, looking in to it

* Delete gitattributes and other theme related items

* all docs need to be moved to /docs * can be changed in the future

* initialize docusaurus repo

* No need to rename the folder! Change a setting and we're all good to go.

docs/src/pages/index.js

danpaul000 · 2020-06-30T19:23:47Z

Open items for integration:

reinstate docs/build.sh for CI with yarn start and/or yarn build and ideally some kind of link checker like we had for mdbook.
Make sure set_solana_release_tag.sh and build-cli-usage.sh are called
For post-merge CI build, where should static files end up living? Currently yarn build puts them in the .gitignore'd docs/build directory.
Need to hook up a publishing tool in CI with perms to write to the solana.com DNS. Currently, @rmshea has done this manually using his personal permissions and the vercel tool. Can this be integrated to be called from buildkite, or a different publishing tool?

I'm not sure what is the right approach to use the native docusaurus versioning setup, which has all versions as separate subdirs, rather than separate branches (https://v2.docusaurus.io/docs/versioning#directory-structure), unless we build this dynamically and push to a docs repo. Their UI for jumping between versions of docs is nice, and doesn't require separate domains, ie beta.docs.solana.com, edge.docs.solana.com. It should look similar to gitbook setup, ie docs.solana.com/v1.2.0, docs.solana.com/v.1.1.0.

@garious I can work on some of this later but don't think I'm going to be able to get it all over the line today. More likely EOW.

CriesofCarrots · 2020-07-02T00:56:08Z

docs/src/css/custom.css

+  --ifm-color-primary-lightest: #abd5c6;
+  --ifm-code-font-size: 95%;
+  --ifm-spacing-horizontal: 1em;
+  --ifm-font-family-base: "Rubik", system-ui, -apple-system, Segoe UI, Roboto, Ubuntu, Cantarell, Noto Sans, sans-serif, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol';


Does our style guide offer any different typefaces for multi-paragraph text? Rubik looks great in small chunks on solana.com, but I find it uncomfortable to read in the context of the docs, especially in dark mode.

@CriesofCarrots let me ask Raj and see what we can do. I agree with this completely. Maybe we can keep Roboto.

@CriesofCarrots let me know if you are a fan of Roboto!

rmshea · 2020-07-02T02:04:27Z

@danpaul000 — let me know what you'd like my help with in terms of addressing your items above.

garious · 2020-07-07T19:37:02Z

@danpaul000, any news here? Is this being worked on someplace else?

* Some fonts are hard to read. Others, not so much. Rubik, you've been sidelined. Roboto, into the limelight! * As much as we all love tutorials, I think we all can navigate around a markdown file. Say goodbye, `mdx.md`.

rmshea requested review from garious, mvines and danpaul000 June 25, 2020 06:12

rmshea force-pushed the remove-mdbook branch from a23cd70 to 99c47f3 Compare June 27, 2020 04:20

rmshea mentioned this pull request Jun 28, 2020

gitbook #8746

Closed

rmshea linked an issue Jun 28, 2020 that may be closed by this pull request

gitbook #8746

Closed

mvines previously requested changes Jun 29, 2020

View reviewed changes

rmshea force-pushed the remove-mdbook branch from 99c47f3 to e86346b Compare June 29, 2020 23:21

rmshea force-pushed the remove-mdbook branch from e86346b to 454c8ff Compare June 30, 2020 17:36

rmshea added 5 commits June 30, 2020 12:03

Remove mdbook infrastructure

e3a38b3

* Delete gitattributes and other theme related items

Move all docs to /docs folder to support Docusaurus

1ef3c7d

* all docs need to be moved to /docs * can be changed in the future

Add Docusaurus infrastructure

b6adf30

* initialize docusaurus repo

Remove trailing whitespace, add support for eslint

dec0a1c

Change Docusaurus configuration to support src

3d08448

* No need to rename the folder! Change a setting and we're all good to go.

rmshea force-pushed the remove-mdbook branch from 7882c7f to 3d08448 Compare June 30, 2020 18:08

danpaul000 reviewed Jun 30, 2020

View reviewed changes

docs/src/pages/index.js Show resolved Hide resolved

CriesofCarrots reviewed Jul 2, 2020

View reviewed changes

rmshea and others added 15 commits July 7, 2020 18:15

Remove unneccessary markdown file, fix type

c9f9219

* Some fonts are hard to read. Others, not so much. Rubik, you've been sidelined. Roboto, into the limelight! * As much as we all love tutorials, I think we all can navigate around a markdown file. Say goodbye, `mdx.md`.

Add Procfile for heroku docs deploy

5537de5

Remove yarn.lock

149200e

Move procfile into docs/

f079df4

Switch procfile from nginx to npm

cef1e71

rm quotes

780f501

Add $PORT to docusaurus start script

855e9c3

fixup procfile

a319989

Move port variable back to Procfile

7f89c22

rm port fro Procfile

aa73b07

Change from web to worker dyno

8b6398f

update portfinder

768d3c2

Try nginx

40b4a8c

User vercel to publish, add build script

63b9467

Dynamically determine correct domain for new docs

670db1f

danpaul000 force-pushed the remove-mdbook branch from db76f57 to 670db1f Compare July 9, 2020 00:27

publish-docs.sh added 6 commits July 8, 2020 18:30

shellcheck

b8241b3

use npm instead of yarn

2050574

fixup sed command

1915038

Add /usr/bin to path for npm

522213a

Build docs without docker

883884e

Move docs job from buildkite to travic

4124891

danpaul000 mentioned this pull request Jul 9, 2020

Move from gitbook to docusaurus, build docs in Travis CI #10970

Merged

rmshea closed this Jul 10, 2020

mvines deleted the remove-mdbook branch December 11, 2021 05:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Remove mdbook, transition docs to Docusaurus #10806

Remove mdbook, transition docs to Docusaurus #10806

rmshea commented Jun 25, 2020

rmshea commented Jun 27, 2020

mvines commented Jun 29, 2020

danpaul000 commented Jun 29, 2020

mvines commented Jun 29, 2020

rmshea commented Jun 29, 2020

rmshea commented Jun 29, 2020

rmshea commented Jun 29, 2020

danpaul000 commented Jun 29, 2020

mvines commented Jun 29, 2020

danpaul000 commented Jun 29, 2020

mvines commented Jun 29, 2020

mvines left a comment

garious commented Jun 30, 2020

garious commented Jun 30, 2020

danpaul000 commented Jun 30, 2020

danpaul000 commented Jun 30, 2020

CriesofCarrots Jul 2, 2020

rmshea Jul 5, 2020

rmshea Jul 8, 2020

CriesofCarrots Jul 8, 2020

rmshea commented Jul 2, 2020

garious commented Jul 7, 2020

Remove mdbook, transition docs to Docusaurus #10806

Remove mdbook, transition docs to Docusaurus #10806

Conversation

rmshea commented Jun 25, 2020

Problem

Summary of Changes

rmshea commented Jun 27, 2020

mvines commented Jun 29, 2020

danpaul000 commented Jun 29, 2020

mvines commented Jun 29, 2020

rmshea commented Jun 29, 2020

rmshea commented Jun 29, 2020

rmshea commented Jun 29, 2020

danpaul000 commented Jun 29, 2020

mvines commented Jun 29, 2020

danpaul000 commented Jun 29, 2020

mvines commented Jun 29, 2020

mvines left a comment

Choose a reason for hiding this comment

garious commented Jun 30, 2020

garious commented Jun 30, 2020

danpaul000 commented Jun 30, 2020

danpaul000 commented Jun 30, 2020

CriesofCarrots Jul 2, 2020

Choose a reason for hiding this comment

rmshea Jul 5, 2020

Choose a reason for hiding this comment

rmshea Jul 8, 2020

Choose a reason for hiding this comment

CriesofCarrots Jul 8, 2020

Choose a reason for hiding this comment

rmshea commented Jul 2, 2020

garious commented Jul 7, 2020