Nord Docs Transition

[arcticicestudio]

➜ Please see the corresponding issue nordtheme/web#132 for tasks on the side of Nord Docs.

I'm hyped and happy that the initial launch of Nord Docs, the shiny new website and documentation of Nord, was finally announced.
The release 0.10.0 marks the last version before the next release (0.11.0) that'll be deployed to the production environment/domain at https://www.nordtheme.com.

Time To Say Goodbye

The currently used website (https://arcticicestudio.github.io/nord) is hosted by GitHub Pages using an deprecated GitBook version with an bare template. It was created some time ago to provide at least a simple website instead of only documenting the project in the README, but this was always planned as a transitional solution.

Shiny New Home

Starting from version 0.11.0, all documentations and content assets will be located and served from Nord Docs, the new single-source-of-truth™.
At the same time with the initial launch of the new website the old site will be wiped completely and replaced by a simple index.html file that includes a <meta http-equiv="refresh" /> element to redirect all users to the new domain.

Other changes

There are also some other changes that'll take place with the transition:

No rendered SassDoc anymore

The Sass color palettes of Nord are currently documented with SassDoc from which a static HTML can be generated. Nord's build tools allow to run this generation and also uses a custom theme for the resulting HTML site. Starting from the transition, the generation of the SassDoc files will be removed from Nord including the development dependency for the custom documentation theme!
Since the sources itself won't change the used documentation syntax is still used and there is no breaking change. This comes with three advantages:

1. Nord maintainers won't be responsible for also keeping these docs up-to-date as well as developing a documentation theme that matches Nord's style.
2. Users will be able to simply generate it on their own using their preferred custom documentation theme.
3. The build process will be simplified and the additional step of deploying the generated docs manually to GitHub Pages is not necessary anymore.

According to the statistics the traffic hits for the SassDoc page was almost dead (95% are search engines and bots) so the impact will be almost invisible.

No optimized CSS module anymore

Currently it is possible to build a optimized CSS module using the npm run optimize:css command. This is done by using the clean-css package to optimize, clean and minify the CSS module and saving it as build/nord.css. This also requires to adjust the import path from node_modules/nord/src/nord.css to node_modules/nord/dist/nord.css.

Since most users are building projects using a bundler like Webpack, which will take care of optimizing the CSS module including the addition of vendor prefixes, it is not necessary to provide such an optimized CSS module. The result of the bundlers are generally more accurate, up-to-date, matches the users preferred optimization rules and ensures it fits the projects data processing flow.

Removing the optimized CSS module comes with the positive effects of also removing more development dependencies.

Lightweight And Simpler

Since all documentations will be served by Nord Docs there is no more need for the docs:dev and docs:build npm commands and the logic that behind them. This includes the deletion of the deprecated GitBooks (dev)dependency and the whole docs directory with the actual Markdown documentation source files.

There are also currently a lot of assets for Nord and all of its port project included in the repository. Most of them will also be moved to Nord Docs (or will be replaced by already existing ones) while many will be deleted since they are not used and required anymore.

All these changes will make Nord more lightweight with and cleaner structure and will simplify the build stack enormously.

Retire Travis CI builds

Since almost all Arctic Ice Studio projects already completely moved to Circle CI as single CI provider Nord will now also retire the Travis CI builds. It is not necessary to run both Circle CI and Travis CI at the same time since the Circle CI API version 2.x is by far more advanced and provides all features of Travis CI.

Statistic Comparison

To get some numbers about all these improvements before and after the migration these are the statistics of the current repository state.

| Name                         | Value     | Level of concern               |
| ---------------------------- | --------- | ------------------------------ |
| Overall repository size      |           |                                |
| * Commits                    |           |                                |
|   * Count                    |   173     |                                |
|   * Total size               |  67.4 KiB |                                |
| * Trees                      |           |                                |
|   * Count                    |   332     |                                |
|   * Total size               |   183 KiB |                                |
|   * Total tree entries       |  4.19 k   |                                |
| * Blobs                      |           |                                |
|   * Count                    |   387     |                                |
|   * Total size               |  58.7 MiB |                                |
| * Annotated tags             |           |                                |
|   * Count                    |     2     |                                |
| * References                 |           |                                |
|   * Count                    |    12     |                                |
|                              |           |                                |
| Biggest objects              |           |                                |
| * Commits                    |           |                                |
|   * Maximum size         [1] |  1.30 KiB |                                |
|   * Maximum parents      [2] |     2     |                                |
| * Trees                      |           |                                |
|   * Maximum entries      [3] |    96     |                                |
| * Blobs                      |           |                                |
|   * Maximum size         [4] |  3.48 MiB |                                |
|                              |           |                                |
| History structure            |           |                                |
| * Maximum history depth      |   154     |                                |
| * Maximum tag depth      [5] |     1     |                                |
|                              |           |                                |
| Biggest checkouts            |           |                                |
| * Number of directories  [6] |    18     |                                |
| * Maximum path depth     [6] |     4     |                                |
| * Maximum path length    [6] |    51 B   |                                |
| * Number of files        [7] |   141     |                                |
| * Total size of files    [7] |  49.9 MiB |                                |
| * Number of symlinks         |     0     |                                |
| * Number of submodules       |     0     |                                |

The report has been generated using GitHub's awesome git-sizer project: git-sizer --verbose

Transition Tasks

This issue documents the tasks and their progress during the transition.

• INTRODUCTION
  • Transfer docs from landing page to new docs about Nord itself and its colors & palettes.
  • Transfer docs from color swatches page to new docs about Nord's color swatches.
  • Delete port project page, it will be replaced by the new ports page.
  • Delete component card, the cards have been implemented as component on the new landing page.
• GETTING STARTED
  • Transfer docs from installation and usage pages to new docs about how to use Nord as color palette and integrate it into other projects.
• DEVELOPMENT
  • Transfer, simplify and squeeze docs from requirements, building and testing pages to new docs about how Nord's development tech stack and the contribution guides.
    ⭢ Planned for later release version since the priority is low.
  • Delete changelog and code-of-conduct pages, they'll be replaced with more advanced pages later on, e.g a interactive changelog timeline and roadmap.
• Remove now unused (dev) dependencies:
  • clean-css-cli
  • cpy-cli
  • del-cli
  • gitbook-cli
  • make-dir-cli
  • sassdoc
  • sassdoc-theme-flippant
• Retire Travis CI builds.
• Update outdated metadata like copyright paragraphs and add missing comment headings.