Add Docusaurus (#67)

* Add Docusaurus

Close #58

* Update Docusaurus ignore files and delete `website/i18n`

* Ignore ESLint issues via comments

* Avoid CI failures by disabling tests

* Add demo page

* Add search bar

* Remove "Processors" (deprecated) from the header

* Add comments to custom CSS

* Add custom CSS `html {overflow-y: auto;}`

* Remove useless `.replace()` call from the generator script

* Auto-generate sidebars.json (especially, for rules list)

* Customize default CSS in demo page via JS

* Fix overflow-y: auto -> scroll

Co-Authored-By: Aleks Hudochenkov <aleks@hudochenkov.com>

* Revert "Customize default CSS in demo page via JS"

This reverts commit 6261253.

* Refactor `generate-stylelint-docs.js`

- Narrow scope of variables.
- Inline variables which are used only once.

* Add `gaTrackingId` to `siteConfig.js`

* Revert "Add `gaTrackingId` to `siteConfig.js`"

This reverts commit 0c9226a.

* Make footer shorter

* Configure `browserslist` in `package.json`

.gitignore

@@ -1,6 +1,14 @@
 /content/
 /dist/
-/node_modules/
+/docs/
+node_modules/
 *.log
 .DS_Store
 package-lock.json
+
+# Docusaurus
+/website/build/
+/website/i18n/*
+/website/sidebars.json
+/website/translated_docs
+/website/yarn.lock

.travis.yml

@@ -3,3 +3,5 @@ sudo: false
 language: node_js
 node_js:
   - 8
+script:
+  - npm run lint

package.json

@@ -24,7 +24,9 @@
     "build": "phenomic build",
     "predeploy": "npm run build",
     "deploy": "gh-pages -t -d dist -r git@github.com:stylelint/stylelint.github.io.git -b master",
-    "watch": "jest --watch"
+    "watch": "jest --watch",
+    "pregendoc": "rimraf docs",
+    "gendoc": "node ./scripts/generate-stylelint-docs docs"
   },
   "phenomic": {
     "assets": false,
@@ -153,6 +155,7 @@
     "file-loader": "^1.1.6",
     "fs-extra": "^5.0.0",
     "gh-pages": "^1.1.0",
+    "glob": "^7.1.4",
     "history": "^2.0.0",
     "husky": "^0.14.3",
     "jest": "^22.0.4",
@@ -178,6 +181,7 @@
     "react-svg-inline": "^2.0.1",
     "react-topbar-progress-indicator": "^2.0.0",
     "redux": "^3.6.0",
+    "remark": "^10.0.1",
     "remark-toc": "^3.1.0",
     "rimraf": "^2.5.4",
     "style-loader": "^0.19.1",

scripts/generate-stylelint-docs.js

@@ -0,0 +1,134 @@
+/* eslint-disable no-console */
+const fs = require("fs");
+const path = require("path");
+const glob = require("glob");
+const remark = require("remark");
+const visit = require("unist-util-visit");
+
+// NOTE: Since Node 10.12.0, `fs.mkdirSync(dir, { recursive: true })` has been supported.
+//
+// If using the version or newer, this utility function can be replaced.
+// See https://github.com/nodejs/node/blob/v10.12.0/doc/changelogs/CHANGELOG_V10.md
+function mkdir_p(dir) {
+  dir.split(path.sep).reduce((parentDir, currentDir) => {
+    const newDir = path.join(parentDir, currentDir);
+    if (!fs.existsSync(newDir)) {
+      fs.mkdirSync(newDir);
+    }
+    return newDir;
+  }, "");
+}
+
+function processMarkdown(file, { rewriter }) {
+  function rewriteLink({ rewriter }) {
+    function visitor(node) {
+      node.url = rewriter(node.url);
+    }
+    function transform(tree) {
+      visit(tree, ["link"], visitor);
+    }
+    return transform;
+  }
+
+  const content = remark()
+    .use(rewriteLink, { rewriter })
+    .processSync(fs.readFileSync(file, "utf8"))
+    .toString();
+
+  // Add Docusaurus-specific fields. See https://docusaurus.io/docs/en/doc-markdown
+  const title = content.match(/\n?# ([^\n]+)\n/)[1];
+  const titleToSidebarLabel = {
+    stylelint: "Home"
+  };
+  const sidebarLabel = titleToSidebarLabel[title] || title;
+  return `---
+title: ${title}
+sidebar_label: ${sidebarLabel}
+hide_title: true
+---
+
+${content}`;
+}
+
+// For Docusaurus. See https://docusaurus.io/docs/en/navigation
+function generateSidebarsJson(outputDir, rulesDir) {
+  const json = JSON.parse(
+    fs.readFileSync(path.join(__dirname, "sidebars-template.json"), "utf8")
+  );
+  json.docs.Rules = fs
+    .readdirSync(path.join(outputDir, rulesDir))
+    .map(filename => `${rulesDir}/${path.basename(filename, ".md")}`)
+    .sort();
+
+  const outputFile = path.join("website", "sidebars.json");
+  fs.writeFileSync(outputFile, JSON.stringify(json, null, 2), "utf8");
+
+  return outputFile;
+}
+
+function main(outputDir) {
+  fs.mkdirSync(outputDir);
+
+  glob.sync("node_modules/stylelint/*.md").forEach(async file => {
+    const output = processMarkdown(file, {
+      rewriter: url =>
+        url.replace(/^\/?docs\//, "").replace("README.md", "index.md")
+    });
+    const outputFile = path.join(
+      outputDir,
+      file
+        .replace("node_modules/stylelint", "")
+        .replace("README.md", "index.md")
+    );
+    mkdir_p(path.dirname(outputFile));
+    fs.writeFileSync(outputFile, output, "utf8");
+    console.log(outputFile);
+  });
+
+  glob.sync("node_modules/stylelint/docs/**/*.md").forEach(file => {
+    const output = processMarkdown(file, {
+      rewriter: url =>
+        url
+          .replace(
+            "../../lib/rules/index.js",
+            "https://github.com/stylelint/stylelint/blob/master/lib/rules/index.js"
+          )
+          .replace("../../VISION.md", "../VISION.md")
+          .replace("../../lib/rules/", "rules/")
+          .replace("/README.md", ".md")
+    });
+    const outputFile = path.join(
+      outputDir,
+      file.replace("node_modules/stylelint/docs", "")
+    );
+    mkdir_p(path.dirname(outputFile));
+    fs.writeFileSync(outputFile, output, "utf8");
+    console.log(outputFile);
+  });
+
+  glob.sync("node_modules/stylelint/lib/rules/**/*.md").forEach(file => {
+    const output = processMarkdown(file, {
+      rewriter: url =>
+        url
+          .replace(/\.\.\/([a-z-]+)\/README.md/, "$1.md")
+          .replace(
+            /\.\.\/\.\.\/\.\.\/docs\/user-guide\/([a-z-]+)\.md/,
+            "../$1.md"
+          )
+    });
+    const outputFile = path.join(
+      outputDir,
+      file
+        .replace("node_modules/stylelint/lib/rules", "user-guide/rules")
+        .replace("/README.md", ".md")
+    );
+    mkdir_p(path.dirname(outputFile));
+    fs.writeFileSync(outputFile, output, "utf8");
+    console.log(outputFile);
+  });
+
+  const sidebarsJson = generateSidebarsJson(outputDir, "user-guide/rules");
+  console.log(`Generated: ${sidebarsJson}`);
+}
+
+main(process.argv[2]);

scripts/sidebars-template.json

@@ -0,0 +1,35 @@
+{
+  "docs": {
+    "Overview": ["index", "VISION", "CHANGELOG", "CONTRIBUTING"],
+    "For users": [
+      "user-guide",
+      "user-guide/faq",
+      "user-guide/about-rules",
+      "user-guide/semantic-versioning-policy",
+      "user-guide/configuration",
+      "user-guide/rules",
+      "user-guide/plugins",
+      "user-guide/processors",
+      "user-guide/example-config",
+      "user-guide/css-processors",
+      "user-guide/cli",
+      "user-guide/node-api",
+      "user-guide/postcss-plugin",
+      "user-guide/complementary-tools",
+      "user-guide/articles"
+    ],
+    "Rules": [],
+    "For developers": [
+      "developer-guide",
+      "developer-guide/prerequisites",
+      "developer-guide/rules",
+      "developer-guide/plugins",
+      "developer-guide/processors",
+      "developer-guide/formatters",
+      "developer-guide/rule-testers",
+      "developer-guide/releases",
+      "developer-guide/pull-requests",
+      "developer-guide/issues"
+    ]
+  }
+}