wip: documentation website

[satya164]

TODO

• [ ] Add syntax highlighting for CSS literals in component-docs
• [ ] Make a homepage for the docs website
• [ ] Publish docs in linaria.now.sh/docs or maybe github pages?
• [ ] Publish docs on CI
• [ ] Add logo in sidebar

[callstack-bot]

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

[jayu]

@satya164 What is the status of it? Should it be closed or can it be continued?

[satya164]

I think someone can pick it up and continue

[trongthanh]

Can I pick this up since we're adopting Linaria for my team project and have the need to check up documentation constantly but current markdown files are not convenient enough.

[satya164]

@trongthanh feel free to pick it up. what I had trouble with is to figure out how to add syntax highlighting for CSS literals and didn't have enough time to investigate. lemme know if we need any changes in component-docs to support it.

[trongthanh]

@satya164,

I've looked into component-docs and the refractor / Prism.js library used beneath for syntax highlighting and found that in order to highlight CSS-in-JS, we need to register the additional language extension js-templates.

I guess they only added this template string highlighting recently and after this PR.

I've tried it with following patch to the highlight.js file:

...
  refractor.register(require('refractor/lang/javascript'));
+ refractor.register(require('refractor/lang/js-extras'));
+ refractor.register(require('refractor/lang/js-templates'));
  refractor.register(require('refractor/lang/typescript'));
...

The optional package js-extras is to support modern ECMAScript syntax and is not related to the CSS-in-JS fix.

Here's proof that it's working:

[satya164]

@trongthanh awesome! would be cool if you added that in a PR and I'll make a release.

[trongthanh]

Before I open a PR, I'd like to clarify my intention regarding renaming of the MD files. So, as per this PR, the markdowns are renamed with order number so that they are deliberately sorted in a file glob pattern. However, with component-docs config file, we can also explicitly define the markdowns order like so:

const path = require('path');

module.exports = {
  pages: [
    { type: 'mdx', file: path.resolve(__dirname, 'docs/HOME.mdx') },
    { type: 'md', file: path.resolve(__dirname, 'docs/GET_STARTED.md') },
    { type: 'md', file: path.resolve(__dirname, 'docs/BASICS.md')},
    { type: 'md', file: path.resolve(__dirname, 'docs/BENEFITS.md')},
    { type: 'md', file: path.resolve(__dirname, 'docs/API.md')},
    { type: 'md', file: path.resolve(__dirname, 'docs/CONFIGURATION.md')},
    { type: 'md', file: path.resolve(__dirname, 'docs/CLI.md')},
    { type: 'md', file: path.resolve(__dirname, 'docs/BUNDLERS_INTEGRATION.md')},
    { type: 'md', file: path.resolve(__dirname, 'docs/LINTING.md')},
    { type: 'md', file: path.resolve(__dirname, 'docs/CRITICAL_CSS.md')},
    { type: 'md', file: path.resolve(__dirname, 'docs/DYNAMIC_STYLES.md')},
    { type: 'md', file: path.resolve(__dirname, 'docs/THEMING.md')},
    { type: 'md', file: path.resolve(__dirname, 'docs/HOW_IT_WORKS.md')},
    { type: 'md', file: path.resolve(__dirname, 'docs/2.0_MIGRATION_GUIDE.md')},
  ]
};

To avoid renaming current markdown files as well as because component-docs is currently having this CLI pages glob issue, I'd like to suggest that we add component-docs.config.js to the project to define the pages structure with it.

The downside is that we have to manually add new entries when there are new MD.

[satya164]

I'll look at the glob issue, but let's keep the config file since we'd want more organization such as sections (Guides, API Reference etc.).

Though would be good to have an array like following and then generate pages array from it:

[
  'Home.mdx',
  'GET_STARTED.md',
  ...
]