Change documentation platform from Docz to MkDocs with Docoff (#373)

.browserslistrc

@@ -3,4 +3,3 @@
 defaults
 not ie > 1
 not ie_mob > 1
-maintained node versions

.env.dist

@@ -0,0 +1,6 @@
+# Host system port where the live documentation is to be made accessible
+COMPOSE_START_PORT=8000
+
+# Ownership of the files created in the container
+COMPOSE_UID=1000
+COMPOSE_GID=1000

.eslintrc

@@ -6,12 +6,12 @@
     "browser": true,
     "jest": true
   },
+  "ignorePatterns": ["src/docs/_assets/generated"],
   "overrides": [
     {
-      "files": ["**/*.md", "**/*.mdx"],
+      "files": ["**/*.md"],
       "extends": [
-        "plugin:markdown/recommended",
-        "plugin:mdx/recommended"
+        "plugin:markdown/recommended"
       ]
     }
   ],

.github/workflows/release-management.yml

@@ -24,7 +24,7 @@ jobs:
         run: npm ci
 
       - name: Build
-        run: npm run build
+        run: docker compose run --rm node_build_site && docker compose run --rm mkdocs_build_site
 
       - name: Test
         run: npm test
@@ -45,7 +45,7 @@ jobs:
         uses: actions/upload-artifact@v3
         with:
           name: docs
-          path: docs
+          path: site
 
   update_release_draft:
     name: Update release draft

.gitignore

@@ -1,6 +1,7 @@
-/.docz
 /dist
-/docs
 /node_modules
-lib-stats.development.html
-lib-stats.html
+/site
+/src/docs/_assets/generated/*
+.env
+statistics.html
+!.gitkeep

.markdownlint.jsonc

@@ -2,9 +2,11 @@
 
 {
   "default": true,
+  "MD033": false, // Allow inline JSX.
+  "MD024": false, // Allow duplicate headings
   "line-length": {
     "code_block_line_length": 120,
-    "tables": false
-  },
-  "no-inline-html": false // Allow inline JSX.
+    "tables": false,
+    "code_blocks": false
+  }
 }

.npmignore

@@ -1,25 +1,29 @@
-/.docz
 /.github
 /.idea
-/docs
+/docker
 /node_modules
-/src/docs/
-/src/gatsby-theme-docz/
+/public
+/site
 /src/**/__tests__
+/src/docs/
+/src/cssCustomProperties.js
+/src/index.md
 /tests
 .browserslistrc
 .editorconfig
+.env
+.env.dist
 .eslintrc
 .gitignore
 .markdownlint.jsonc
 babel.config.js
-doczrc.js
-gatsby-config.js
+CONTRIBUTING.md
+docker-compose.yml
 jest.config.js
-lib-stats.development.html
-lib-stats.html
+mkdocs.yml
 package-lock.json
 postcss.config.js
 RELEASING.md
+statistics.html
 stylelint.config.js
-webpack.config.js
+webpack.config.babel.js

CONTRIBUTING.md

@@ -1,24 +1,83 @@
----
-name: General Guidelines
-route: /contribute/guidelines
-menu: Contribute
----
-
 # Contributing
 
 In the first place, thank you for your interest in contributing! 🙏
 
 ## Development
 
-To build the project:
+Working on the site requires:
+
+* [Docker]
+* [Docker Compose]
+
+This allows running the documentation site which serves as a development platform.
+
+### Configure Docker Compose
+
+Review the default env variable values in the `docker-compose.yml` file.
+The defaults should work for most systems, but can be changed if needed.
+
+To change them:
+
+1. Create a `.env` file from the template:
+
+    ```bash
+    cp .env.dist .env
+    ```
+
+2. Edit the new `.env` file as needed
+
+### Use Docker Compose
+
+#### Node shell
+
+All npm commands such as `npm ci`, `npm test`, `npm run eslint` and others you
+need to run them within the `node_shell` docker container.
+
+To log into the container, run:
+
+```bash
+docker compose run --rm node_shell
+```
+
+#### Run the Dev Server
+
+1. Install dependencies (run within `node_shell`):
+
+    ```bash
+    npm ci
+    ```
+
+2. Run development server (run on host):
+
+    ```bash
+    docker compose up node_dev_server mkdocs_dev_server
+    ```
+
+#### Build the Project
+
+1. Make sure the dev server is not running (run on host):
+
+    ```bash
+    docker compose down
+    ```
 
-1. Install local npm packages: `npm install`
-2. Run the build: `npm run build`
+2. Install dependencies (run within `node_shell`):
 
-To run the dev server:
+    ```bash
+    npm ci
+    ```
 
-1. Install local npm packages: `npm install`
-2. Run the dev server (usually on `http://localhost:3000`): `npm start`
+3. Build JS (run on host):
+
+    ```bash
+    docker compose run --rm node_build_site
+    ```
+
+4. Build mkDocs (run on host):
+
+    ```bash
+    docker compose run --rm mkdocs_build_site
+    ```
 
 ## Git Workflow
 
@@ -33,41 +92,42 @@ Actions), please follow these guidelines:
 
 3. **Name your branches according to nature of change.** Choose one of:
 
-   - `bc/*` for breaking changes
-   - `feature/*` for features
-   - `bugfix/*` for bugfixes
-   - `refactoring/*` for refactoring of the library
-   - `docs/*` or `documentation/*` for changes in docs
-   - `maintenance/*` for maintenance (builds, dependencies, automation, etc.)
-   - `release/*` for [releases](/contribute/releasing) (administrators only)
+    * `bc/*` for breaking changes
+    * `feature/*` for features
+    * `bugfix/*` for bugfixes
+    * `refactoring/*` for refactoring of the library
+    * `docs/*` or `documentation/*` for changes in docs
+    * `maintenance/*` for maintenance (builds, dependencies, automation, etc.)
+    * `release/*` for releases (administrators only)
 
 4. **Write clear, helpful and descriptive commit messages.**
 
-   1. **Use imperative and write in English,** e.g. _Update dependencies_ or
-      _Claim support for controlled components only_.
-   2. **If an issue exists for your changes, append the issue number** in
-      parentheses to the end of the commit message, e.g. _Update dependencies
-      (#261)_.
-   3. Optionally use Markdown code blocks to emphasize, e.g.
-      _Create `ScrollView` component (#53)_.
+    1. **Use imperative and write in English,** e.g. _Update dependencies_ or
+       _Claim support for controlled components only_.
+    2. **If an issue exists for your changes, append the issue number** in
+       parentheses to the end of the commit message, e.g. _Update dependencies
+       (#261)_.
+    3. Optionally use Markdown code blocks to emphasize, e.g.
+       _Create `ScrollView` component (#53)_.
 
 5. **Write clear, helpful and descriptive PR names.**
 
-   1. **All rules for commit messages apply** also for PR names.
-   2. **Always check that PR name meets the requirements** above because **PR
-      names are used in changelog**. GitHub automatically truncates long PR
-      names and picks up branch name for multi-commit PRs, so it's necessary to
-      make sure the PR name is what we want to have in the changelog.
-   3. **If an issue exists for your changes, append this text to PR
-      description** (the topmost comment in the PR) in order for the issue to be
-      closed automatically once the PR is merged: `Closes #<ISSUE NUMBER>`. You
-      will know the issue is linked correctly when it appears in the _Linked
-      issues_ section of the PR. (Having the issue mentioned in commit message
-      and/or PR name does _not_ have this effect.)
-   4. **If there is no issue for your changes, please add your PR to `The
-      Board`** GitHub project in the _Projects_ section of the PR. The correct
-      board column will be selected automatically. This helps us keep track of
-      what is in development.
+    1. **All rules for commit messages apply** also for PR names.
+    2. **Always check that PR name meets the requirements** above because **PR
+       names are used in changelog**. GitHub automatically truncates long PR
+       names and picks up branch name for multi-commit PRs, so it's necessary to
+       make sure the PR name is what we want to have in the changelog.
+    3. **If an issue exists for your changes, append this text to PR
+       description** (the topmost comment in the PR) in order for the issue
+       to be
+       closed automatically once the PR is merged: `Closes #<ISSUE NUMBER>`. You
+       will know the issue is linked correctly when it appears in the _Linked
+       issues_ section of the PR. (Having the issue mentioned in commit message
+       and/or PR name does _not_ have this effect.)
+    4. **If there is no issue for your changes, please add your PR to `The
+       Board`** GitHub project in the _Projects_ section of the PR. The correct
+       board column will be selected automatically. This helps us keep track of
+       what is in development.
 
 Pull requests are labelled automatically. You can add more labels to better
 qualify the nature of the change — in such case, it will be included in all
@@ -82,9 +142,8 @@ application with `npm link` so you can see it in action.
 1. In React UI repository, run `npm link`
 2. In your application, run `npm link @react-ui-org/react-ui`
 
-To prevent
-[Invalid Hook Call Warning](https://reactjs.org/warnings/invalid-hook-call-warning.html#duplicate-react)
-when React UI is linked, add the following code to your app's Webpack config:
+To prevent [Invalid Hook Call Warning][react-invalid-hook] when React UI is
+linked, add the following code to your app's Webpack config:
 
 ```js
 const path = require('path');
@@ -108,30 +167,13 @@ To keep React UI consistent and predictable the following guidelines should be o
 
 ## Documenting
 
-We use [Docz](https://docz.site) (powered by [Gatsby](https://www.gatsbyjs.com))
-as the documentation platform. The documentation itself is written in
-[MDX](https://mdxjs.com) format — a human-readable blend of the popular Markdown
-and JSX syntax.
-
-Run `npm start` to run the docs in development mode, and open
-`http://localhost:3000` in your browser to see the docs in live-reload mode.
-
-A few things to note:
-
-- In order to get component props parsed and rendered by Docz, it's crucial to
-  **import the component into an MDX file right from its source file** — parsing
-  a re-exported component (typically via `index.js`) isn't currently supported.
-
-- If you don't want Gatsby to collect **anonymous statistics**, you may want to
-  disable [Gatsby telemetry](https://www.gatsbyjs.com/docs/telemetry/) by
-  running `npx gatsby telemetry --disable`.
+We use combination of [Material for MkDocs][mkdocs-material] and [Docoff] as
+the documentation platform.
 
-- If you see the Not found page after having **changed the configuration of Docz
-  or Gatsby in the live-reload mode,** you may either restart the Docz
-  development server (`ctrl + c` and `npm start`), or try to edit an MDX file
-  which makes the Docz rebuild, too.
+Do see their respective documentation for details.
 
-- To **make your authoring experience better,** we recommend to make sure your
-  IDE understands the MDX syntax and is able to help you wrap lines in MD and
-  MDX files automatically (Jetbrains IDE's and VSCode support both features
-  out-of-the-box or through a plugin).
+[Docker]: https://www.docker.com
+[Docker Compose]: https://docs.docker.com/compose/
+[react-invalid-hook]: https://reactjs.org/warnings/invalid-hook-call-warning.html#duplicate-react
+[mkdocs-material]: https://squidfunk.github.io/mkdocs-material/
+[Docoff]: https://github.com/react-ui-org/docoff

README.md

@@ -10,7 +10,7 @@ React UI is a themeable, performant, responsive UI library for React apps.
 Use it simply with no configuration or have full control over your design by
 tweaking some of the hundreds theming options available.
 
-**[Explore React UI docs →](https://react-ui.io)**
+**[Explore React UI docs →][rui-docs]**
 
 ## Key Concepts
 
@@ -38,7 +38,7 @@ these requirements:
 </p>
 
 > Development of React UI is largely supported by
-> [RACOM](https://www.racom.eu)—one of the leading global players in wireless
+> [RACOM]—one of the leading global players in wireless
 > Critical Infrastructure.
 
 ## Quick Start Guide
@@ -81,8 +81,7 @@ To install React UI in your app:
    <Button label="My Button" />
    ```
 
-Head to [the docs](https://react-ui.io) to see how to use, customize, and
-extend React UI.
+Head to [the docs][rui-docs] to see how to use, customize, and extend React UI.
 
 ### Development Mode
 
@@ -114,6 +113,9 @@ Then run webpack with the `--mode=production` or `--mode=development` flag.
 
 We appreciate any contributions you might make. 🙏
 
-Please check out our
-[Contributing Guide](https://react-ui.io/contribute/guidelines). It includes
+Please check out our [Contributing Guide][gh-contributing]. It includes
 contribution guidelines and information on how to run and develop the project.
+
+[rui-docs]: https://react-ui.io
+[RACOM]: https://www.racom.eu
+[gh-contributing]: https://github.com/react-ui-org/react-ui/blob/master/CONTRIBUTING.md