Change documentation platform from Docz to Docoff

.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,6 +6,7 @@
     "browser": true,
     "jest": true
   },
+  "ignorePatterns": ["src/docs/_assets/generated"],
   "overrides": [
     {
       "files": ["**/*.md", "**/*.mdx"],

.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,6 @@
-/.docz
 /dist
-/docs
 /node_modules
-lib-stats.development.html
-lib-stats.html
+/site
+/src/docs/_assets/generated/*
+.env
+!.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,10 +1,10 @@
-/.docz
 /.github
 /.idea
-/docs
+/docker
 /node_modules
+/public
+/site
 /src/docs/
-/src/gatsby-theme-docz/
 /src/**/__tests__
 /tests
 .browserslistrc
@@ -13,13 +13,12 @@
 .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
 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,13 +92,13 @@ 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.**
 
@@ -82,9 +141,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 +166,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

RELEASING.md

@@ -1,24 +1,18 @@
----
-name: Releasing
-route: /contribute/releasing
-menu: Contribute
----
-
 # Releasing
 
 The release process is fully automated so you can release a new version just
 by bumping version number in `package.json`. However, there are several chances
 to adjust both version and changelog if you wish to do so for a reason.
 
 In order for the automation to work properly, contributors must follow the
-[contributing guidelines](/contribute/guidelines).
+[contributing guidelines][gh-contributing].
 
 ## How It Works
 
 1. Pull requests are automatically labelled by branch name. Labels are then used
    for:
 
-   1. resolving next [semantic version number](https://semver.org)
+   1. resolving next [semantic version number][semver]
       (BREAKING.FEATURE.PATCH),
    2. grouping changes in changelog.
 
@@ -31,11 +25,11 @@ See the source of `.github/workflows` for details.
 ## Release Process
 
 1. **As you go:** make sure all contributions follow the contributing
-   guidelines, especially the
-   [Git workflow](/contribute/guidelines#git-workflow) (correct PR names and
-   branch names). Check out the release draft on
-   [GitHub releases page](https://github.com/react-ui-org/react-ui/releases) to
-   see what the changelog looks like and what will be the next version number.
+   guidelines, especially the [Git workflow][gh-contributing-git] (correct
+   PR names and branch names). Check out the release draft on
+   [GitHub releases page][gh-releases] to see what the changelog looks like and
+   what will be the next version number.
+
    **Don't edit manually until you are ready to publish the release.** Release
    draft is automatically overwritten everytime a change is merged to `master`.
 
@@ -68,3 +62,8 @@ See the source of `.github/workflows` for details.
 
 **Note:** prefix version number with `v` everywhere except in `package.json` and
 `package-lock.json`.
+
+[semver]: https://semver.org
+[gh-contributing]: https://github.com/react-ui-org/react-ui/blob/master/CONTRIBUTING.md
+[gh-contributing-git]: https://github.com/react-ui-org/react-ui/blob/master/CONTRIBUTING.md#git-workflow
+[gh-releases]: https://github.com/react-ui-org/react-ui/releases

docker-compose.yml

@@ -0,0 +1,33 @@
+services:
+  # Base services - do not run directly
+  mkdocs:
+    build: docker/mkdocs
+    user: ${COMPOSE_UID-1000}:${COMPOSE_GID-1000}
+    volumes:
+      - .:/workspace:z
+  node:
+    build: docker/node
+    user: ${COMPOSE_UID-1000}:${COMPOSE_GID-1000}
+    volumes:
+      - .:/workspace:z
+
+  # Dev services
+  mkdocs_dev_server:
+    extends: mkdocs
+    entrypoint: mkdocs serve
+    ports:
+      - ${COMPOSE_START_PORT-8000}:8000
+  node_dev_server:
+    extends: node
+    entrypoint: npm start
+  node_shell:
+    extends: node
+    entrypoint: bash
+
+  # Build services
+  mkdocs_build_site:
+    extends: mkdocs
+    entrypoint: mkdocs build
+  node_build_site:
+    extends: node
+    entrypoint: npm run build

docker/mkdocs/Dockerfile

@@ -0,0 +1,8 @@
+FROM            node:16
+
+RUN             apt-get update && apt-get install -y python3-pip
+RUN             pip3 install 'mkdocs-material>=9.0.0,<10.0.0'
+RUN             mkdir /workspace
+
+COPY            ./init-container.sh /root/init-container.sh
+WORKDIR         /workspace