WIP: Documentation site using component-docs #692
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.
Motivation
As per discussion in #320, here's my initial PR follow up what's left in #320 and it is still a WIP.
Summary
Here's my list of features that I think needed to done (details in RFC below):
Details and RFC
Syntax highlighting of CSS in string literals is fixed in feat: enable highlighting js tagged template literals and modern js syntax component-docs#45 but then it's blocked by Packages upgrade in v0.24.0 introduce many breaking changes component-docs#49. I'm pending for component-docs author to clear the blocking issue first.
Currently, some React components in the
docs
folder which is used by the MDX document are written with Flow type. I want to port them to TypeScript but also need to check if component-docs has already support TS.My initial intention is to generate the docs site to
website/docs
folder and add a static serving middleware to Koa server. However when I try to output the component-docs site intowebsite/docs
, I get some React runtime mismatch error.So, currently, the documentation site is generated to
docs-public
folder. I'll look into how website is built right now and will suggest a patch so that docs site will be served at linaria.dev/docsWith whatever Linaria repo CI/CD solution currently is, add a step to generate docs site and serve it to website at
/docs
Pick some sections in README, for e.g.: Features, Setup, Syntax, Demo, Trade-off... and copy them to docs site Home Page.
Use a client-side text search solution for example lunr.js to provide better documentation browsing. This might be too complicated and should be in another PR.
Test plan
I have created a Netlify deployment automatically built upon new commits pushed to this branch. Everyone can preview it here: https://linaria-docs-preview.netlify.app
Contributors can check out the branch, re-run yarn install and execute
yarn docs
to build and serve the site at http//localhost:3031