Design Concept & Initial Launch Plan #1
Assignees
Comments
This was referenced Oct 1, 2018
This was referenced Dec 16, 2018
9 tasks
arcticicestudio
added a commit
to nordtheme/nord
that referenced
this issue
Mar 16, 2019
I'm hyped and happy that the initial launch (1) of Nord Docs, the shiny new website and documentation of Nord, was finally announced (2). The release 0.10.0 (3) 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 previously used website (4) (https://arcticicestudio.github.io/nord) was hosted by GitHub Pages (5) 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 are 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 took place with this transition: >>> No rendered SassDoc anymore The Sass color palettes of Nord were documented with SassDoc from which a static HTML was generated. Nord's build tools allowed 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 have been removed from Nord including the development dependency for the custom documentation theme! Since the sources itself are not changed the used documentation syntax is still used and there is no breaking change. This comes with three advantages: 1. Nord maintainers are not responsible for also keeping these docs up-to-date as well as developing a documentation theme that matches Nord's style. 2. Users are able to simply generate it on their own using their preferred custom documentation theme. 3. The build process has been 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 is almost invisible. >>> No optimized CSS module anymore Previously it was possible to build a optimized CSS module (6) using the `npm run optimize:css` command. This was done by using the clean-css (7) package to optimize, clean and minify the CSS module and saving it as `build/nord.css`. This also required 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 (8), which takes 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 (9). Most of them have also been moved to Nord Docs (or will be replaced by already existing ones) while many have been deleted since they are not used and required anymore. All these changes made Nord more lightweight with and cleaner structure and simplified the build stack enormously. >> Statistic Comparison ```raw | 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 (11): `git-sizer --verbose` References: (1) nordtheme/web#1 (2) https://twitter.com/arcticicestudio/status/1104494647383068673 (3) https://github.com/arcticicestudio/nord-docs/releases/tag/v0.10.0 (4) https://arcticicestudio.github.io/nord (5) https://pages.github.com (6) https://arcticicestudio.github.io/nord/development/building.html#optimized-css-module (7) https://www.npmjs.com/package/clean-css (8) https://webpack.js.org (9) https://github.com/arcticicestudio/nord/tree/develop/assets (10) https://github.com/github/git-sizer GH-112
This was referenced Nov 7, 2020
This was referenced Jun 6, 2021
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
This epic documents the project concept and serves as a plan for the initial launch. It defines the web design process in several steps this project will go through. It is also the main issue to track all related sub-epics that contain detailed documentations about the concepts described in this issue.
Project Justification
The main reason to start this project is to create a „single source of truth“ for information, assets and resources of the Nord project and all of its ports. There are currently more than 35 repositories providing ports of Nord to various applications and platforms where each project is mostly self-contained regarding its source and documentation. However, there is always a correlation to the main project, the color palette itself, that makes it necessary to link between repositories or even include some assets of these.
On the other hand, the main repository need to keep references to all of its port projects making it time consuming to adapt to changes like documentations. Many port project repositories currently include both the code and documentation sources and even host them at the same time e.g. with GitHub Pages through a dedicated
gh-pagesbranch.Another important reason is the fact that there are currently no clear communication channels to publish information and news about the project. Instead, these are distributed across different media like Twitter, Slack, Reddit and Keybase (Chat). These channels will also get more attention to build up a more connected community where users can help each other. This should improve the current situation where users need to open a “support“ issue on the repository to get help with e.g. their setup problems. Instead, they can join one of the channels and in the best case get immediate help. I also hope to reduce the support / management overhead I currently have to deal with (which costs almost 80% of the time I can work on the projects) and concentrate more on development.
The site will be created as the the „single source of truth“ and bundle all information. The listed channels above and a new project blog are then used to announce and link new site content. This will also allow to create extensive and customized content instead of being limited to the possibilities of the respective platform.
Goals
This section contains what goals the site needs to fulfill and what its purpose. It should…
Architecture
Nord Docs will be designed and compliant to JAMstack, a modern web development architecture based on client-side JavaScript, reusable APIs, and prebuilt Markup.
The detailed design concept and all tracked implementation issues are documented in #24.
Technologies
This section lists the technologies that will be used to build the site. The detailed design concepts are documented in the related epics linked in each section.
UI
Nord Docs UI will be build with Gatsby, the blazing fast modern site generator to build secure, modern and blazing fast websites and apps with React. It is fully compliant to JAMstack which is the web development architecture used to built Nord Docs as documented in #24.
The detailed design concept and all tracked implementation issues are documented in #25.
Styling
Since the website will be build with React the whole styling with the CSS-in-JS technique using one of the most popular libraries styled-components.
Content
To use the great power of React, Nord Docs will make use of the MDX specification, a new language and abstract syntax tree definition. It be integrated through the official implementation, a fully-featured MDX parser, loader and JSX renderer to allow to seamlessly use JSX in Markdown documents by importing components and export metadata or any other ECMAScript compliant data structures like frontmatter.
The detailed design concept and all tracked implementation issues are documented in #24 in the Markup section.
Data Sources
Thanks to GraphQL API provide by Gatsby, every data source can be used whether it is from headless CMSs, SaaS services, APIs, databases or the file system: It can be pulled directly into the pages using GraphQL.
When it comes to fire up dynamic REST API requests (not during build time), the popular axios library will be used.
Hosting
The website will be hosted on a dedicated domain with Netlify, the all-in-one workflow that combines global deployment, continuous integration, and automatic HTTPS to build, deploy, and manage modern web projects. It's a awesome provider that invests a lot into the open source community and sets new standards for web development for JAMstack based projects.
The detailed design concept and all tracked implementation issues are documented in #46.
UI Design and Branding
A detailed and extensive design documentation will be linked as soon as it is available, but a short description is that the site will follow a simple, uncluttered and clear design.
Resources
There are a lot of resources, information and inspirations that can be found in the web, whether it's other great websites, well-written articles/blogs or other awesome OSS projects.
This is a listing of some of the resource that have been used for the planing and concept processes described in this issue:
The text was updated successfully, but these errors were encountered: