Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

WIP: Documentation site using component-docs #692

Open
wants to merge 4 commits into
base: master
Choose a base branch
from

Conversation

trongthanh
Copy link
Contributor

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):

  • 1. Syntax highlight of CSS-in-JS
  • 2. Port MDX components from flow to typescript
  • 3. Generate docs site into main website and serve as static
  • 4. CI config for Docs site and as a step of website build
  • 5. Write up home page
  • 6. Improve component-docs filter function to some simple text search

Details and RFC

  1. 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.

  2. 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.

  3. 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 into website/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/docs

  4. With whatever Linaria repo CI/CD solution currently is, add a step to generate docs site and serve it to website at /docs

  5. Pick some sections in README, for e.g.: Features, Setup, Syntax, Demo, Trade-off... and copy them to docs site Home Page.

  6. 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

@callstack-bot
Copy link

Hey @trongthanh, thank you for your pull request 🤗.
The coverage report for this branch can be viewed here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants