Merge pull request #157 from morfeojs/chore/docs-improvement

chore: contributing documentation improvement

CONTRIBUTING.md

@@ -52,7 +52,38 @@ People _love_ thorough bug reports. I'm not even kidding.
 
 By contributing, you agree that your contributions will be licensed under its MIT License.
 
+## Getting started with the project
+
+The following instructions will help you bootstrap the project and start to contribute to Morfeo, thank you for your help!
+If there are any problems, feel free to contact the maintainers.
+
+If you're looking to contribute to the Morfeo libraries, you're in the right place, if instead, you're looking to contribute to the documentation website or the browser extension, you'll find more specific GUIDELINES inside the folders [docs](./docs/README.md) and [devtool](./devtool/README.md).
+
+Other then unit/integration tests, you can use the projects under the folder `examples` to test your changes.
+Feel free to update them or use them as a **sandbox**, but remember to build the packages if yuo want to see the changes you've made!
+
+### Install the dependencies
+
+By running the script `yarn reset` all the dependencies will be installed, packages dependencies included, the script will also trigger the builds of the packages.
+
+### Build the packages
+
+```bash
+yarn build
+```
+
+### Run the tests
+
+To run the tests run the script `yarn test`.
+If you also want to generate the coverage, you can run `yarn run test:coverage`.
+In case you're working on something and you'd like to watch for file changes, `yarn test:watch` is available.
+To test a specific package you can pass to any of the previous scripts the path of the package, for example:
+
+```bash
+yarn test:watch packages/core
+```
+
 ## References
 
 This document was adapted from [this gist](https://gist.github.com/briandk/3d2e8b3ec8daf5a27a62).
-Special thanks to [briandk](https://gist.github.com/briandk).
+Special thanks to [briandk](https://github.com/briandk).

devtool/README.md

@@ -1,9 +1,12 @@
+# Morfeo Browser Extension
+
 ![Morfeo logo](https://morfeo.dev/img/morfeo.png)
 
-[morfeo](https://morfeo.dev) is a framework-agnostic set of tools that will help you to build your next <strong>design system</strong> based on a single source of truth: the **theme**.
+[morfeo](https://morfeo.dev) is a framework-agnostic set of tools that will help you to build your next **design system** based on a single source of truth: the **theme**.
 
 ---
 
+[![Made with Morfeo](https://img.shields.io/badge/made%20with%20morfeo-0066ff?logo=data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPHN2ZyB2aWV3Qm94PSIxOTAuMjIyIDE3OS4xMjkgNTAgNTAuMDA0IiB3aWR0aD0iNTAiIGhlaWdodD0iNTAuMDA0IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPgogIDxwYXRoIGQ9Ik0yNy41NzIsNDcuOTIxbDAsMGwxOC40NSwtMTguNDExYzAuMDQ3LC0wLjA1MSAwLjA5NywtMC4xMDEgMC4xNDgsLTAuMTQ4bDAsMGwwLDBjMC40NjMsLTAuNDI2IDEuMDgxLC0wLjY4NyAxLjc1OSwtMC42ODdjMS40MzQsMCAyLjU5OCwxLjE2NSAyLjU5OCwyLjU5OGwwLDE2LjEzMWMwLDEuNDM0IC0xLjE2NCwyLjU5OCAtMi41OTgsMi41OThsLTQ0LjgwNCwwYy0xLjQzNCwwIC0yLjU5OCwtMS4xNjQgLTIuNTk4LC0yLjU5OGwwLDBjMCwwIDAsLTE2LjEzMSAwLC0xNi4xMzFjMCwtMS40MzMgMS4xNjQsLTIuNTk4IDIuNTk4LC0yLjU5OGMwLjc1MSwwIDEuNDI5LDAuMzIgMS45MDMsMC44M2wwLDBsMTguNDUxLDE4LjQxNmMwLjM0MSwwLjM1NiAxLjIxNiwwLjk5NyAyLjA0NywwLjk5N2MwLjgzLDAgMS41MjMsLTAuNDkgMi4wNDYsLTAuOTk3WiIgc3R5bGU9ImZpbGw6IHJnYigyNTUsIDI1NSwgMjU1KTsiIHRyYW5zZm9ybT0ibWF0cml4KDEsIDAsIDAsIDEsIDE4OS42OTUxNzUsIDE3OS4xMzA1NTQpIi8+CiAgPHBhdGggZD0iTTQ3LjI0NCwwLjAwMmMwLjA1NCwtMC4wMDIgMC4xMDgsLTAuMDA0IDAuMTYyLC0wLjAwNGMwLjA1NCwwIDAuMTA4LDAuMDAyIDAuMTYxLDAuMDA0bDAuMDAxLDBjMS41OTksMC4wODUgMi44NzEsMS40MSAyLjg3MSwzLjAyOWMwLDAuOTE3IC0wLjQwOCwxLjczOSAtMS4wNTEsMi4yOTVsMCwwbC0yMS43OSwyMS43OWMtMC41NDIsMC41MDYgLTEuMjc2LDAuODE1IC0yLjA3NCwwLjgxNWMtMC45MDcsMCAtMS43MzEsLTAuNCAtMi4yODcsLTEuMDMxbC0yMS42NTksLTIxLjY3MWwwLDBjLTAuNTgxLC0wLjU1MiAtMC45NDQsLTEuMzMzIC0wLjk0NCwtMi4xOThjMCwtMS42NzQgMS4zNTksLTMuMDMzIDMuMDMzLC0zLjAzM2MwLjA1NSwwIDAuMTA5LDAuMDAyIDAuMTYyLDAuMDA0bDAsMGw0My40MTUsMFoiIHN0eWxlPSJmaWxsOiByZ2IoMjU1LCAyNTUsIDI1NSk7IiB0cmFuc2Zvcm09Im1hdHJpeCgxLCAwLCAwLCAxLCAxODkuNjk1MTc1LCAxNzkuMTMwNTU0KSIvPgo8L3N2Zz4=)](https://morfeo.dev)
 [![codecov](https://codecov.io/gh/morfeojs/morfeo/branch/main/graph/badge.svg?token=CZBHY8J802)](https://codecov.io/gh/morfeojs/morfeo)
 [![Codecov](https://github.com/morfeojs/morfeo/actions/workflows/codecov.yml/badge.svg)](https://github.com/morfeojs/morfeo/actions/workflows/codecov.yml)
 [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
@@ -14,6 +17,61 @@
 
 ---
 
-[Documentation](https://morfeo.dev) | [API](https://github.com/morfeojs/morfeo) | [Contributing](https://github.com/morfeojs/morfeo/blob/main/CONTRIBUTING.md) | [Slack](https://morfeo.slack.com)
+## Preview
 
----
+> Click the image to watch the video on youtube!
+
+[![Morfeo Web Extension](https://img.youtube.com/vi/UNWGBnmoE9c/maxresdefault.jpg)](https://www.youtube.com/watch?v=UNWGBnmoE9c)
+
+## Installation
+
+From the root of the project (one folder above this one), run:
+
+```console
+yarn init:devtool
+```
+
+### ⚠️ Warning
+
+If you run `yarn` directly in this folder you'll install the published version of the internal `@morfeo` packages,
+this means that you'll not be able to see your changes in case you made updates in one o more packages.
+By running `yarn init:devtool` instead, the internal `@morfeo` packages will be symlinked to reflect your changes.
+
+## Local Development
+
+```console
+yarn start
+# Or, from the root of this project (one folder above this one)
+yarn start:devtool
+```
+
+This command starts a local development server, most changes are reflected live without having to restart the server.
+
+If is the first time you're running the project you have to manually install the extension in your browser.
+
+### Install the web extension
+
+- Run `yarn start`, a new folder called `dev` will be created;
+- Open the Extension Management page by navigating to `chrome://extensions` (This extension works for now only with Chrome or any other chromium-like browser, like Brave);
+  - Alternatively, open this page by clicking on the Extensions menu button and selecting Manage Extensions at the bottom of the menu.
+  - Alternatively, open this page by clicking on the Chrome menu, hovering over More Tools then select Extensions
+- Click on `Load an unpacked extension`
+- Select the `dev` folder
+
+More info [here](https://developer.chrome.com/docs/extensions/mv3/getstarted/#unpacked).
+
+## Build Theme
+
+This extension uses Morfeo in 2 different ways, at run-time to show the theme of the website and at build-time, with compiled css
+created thuogh the CLI.
+If you update the theme (located at `src/_shared/styles`), be sure to also run:
+
+```console
+yarn build:theme
+```
+
+## Build
+
+```console
+yarn build
+```

docs/README.md

@@ -1,17 +1,44 @@
-# Website
+# Morfeo Documentation Website
+
+![Morfeo logo](https://morfeo.dev/img/morfeo.png)
+
+[morfeo](https://morfeo.dev) is a framework-agnostic set of tools that will help you to build your next **design system** based on a single source of truth: the **theme**.
+
+---
+
+[![Made with Morfeo](https://img.shields.io/badge/made%20with%20morfeo-0066ff?logo=data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPHN2ZyB2aWV3Qm94PSIxOTAuMjIyIDE3OS4xMjkgNTAgNTAuMDA0IiB3aWR0aD0iNTAiIGhlaWdodD0iNTAuMDA0IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPgogIDxwYXRoIGQ9Ik0yNy41NzIsNDcuOTIxbDAsMGwxOC40NSwtMTguNDExYzAuMDQ3LC0wLjA1MSAwLjA5NywtMC4xMDEgMC4xNDgsLTAuMTQ4bDAsMGwwLDBjMC40NjMsLTAuNDI2IDEuMDgxLC0wLjY4NyAxLjc1OSwtMC42ODdjMS40MzQsMCAyLjU5OCwxLjE2NSAyLjU5OCwyLjU5OGwwLDE2LjEzMWMwLDEuNDM0IC0xLjE2NCwyLjU5OCAtMi41OTgsMi41OThsLTQ0LjgwNCwwYy0xLjQzNCwwIC0yLjU5OCwtMS4xNjQgLTIuNTk4LC0yLjU5OGwwLDBjMCwwIDAsLTE2LjEzMSAwLC0xNi4xMzFjMCwtMS40MzMgMS4xNjQsLTIuNTk4IDIuNTk4LC0yLjU5OGMwLjc1MSwwIDEuNDI5LDAuMzIgMS45MDMsMC44M2wwLDBsMTguNDUxLDE4LjQxNmMwLjM0MSwwLjM1NiAxLjIxNiwwLjk5NyAyLjA0NywwLjk5N2MwLjgzLDAgMS41MjMsLTAuNDkgMi4wNDYsLTAuOTk3WiIgc3R5bGU9ImZpbGw6IHJnYigyNTUsIDI1NSwgMjU1KTsiIHRyYW5zZm9ybT0ibWF0cml4KDEsIDAsIDAsIDEsIDE4OS42OTUxNzUsIDE3OS4xMzA1NTQpIi8+CiAgPHBhdGggZD0iTTQ3LjI0NCwwLjAwMmMwLjA1NCwtMC4wMDIgMC4xMDgsLTAuMDA0IDAuMTYyLC0wLjAwNGMwLjA1NCwwIDAuMTA4LDAuMDAyIDAuMTYxLDAuMDA0bDAuMDAxLDBjMS41OTksMC4wODUgMi44NzEsMS40MSAyLjg3MSwzLjAyOWMwLDAuOTE3IC0wLjQwOCwxLjczOSAtMS4wNTEsMi4yOTVsMCwwbC0yMS43OSwyMS43OWMtMC41NDIsMC41MDYgLTEuMjc2LDAuODE1IC0yLjA3NCwwLjgxNWMtMC45MDcsMCAtMS43MzEsLTAuNCAtMi4yODcsLTEuMDMxbC0yMS42NTksLTIxLjY3MWwwLDBjLTAuNTgxLC0wLjU1MiAtMC45NDQsLTEuMzMzIC0wLjk0NCwtMi4xOThjMCwtMS42NzQgMS4zNTksLTMuMDMzIDMuMDMzLC0zLjAzM2MwLjA1NSwwIDAuMTA5LDAuMDAyIDAuMTYyLDAuMDA0bDAsMGw0My40MTUsMFoiIHN0eWxlPSJmaWxsOiByZ2IoMjU1LCAyNTUsIDI1NSk7IiB0cmFuc2Zvcm09Im1hdHJpeCgxLCAwLCAwLCAxLCAxODkuNjk1MTc1LCAxNzkuMTMwNTU0KSIvPgo8L3N2Zz4=)](https://morfeo.dev)
+[![codecov](https://codecov.io/gh/morfeojs/morfeo/branch/main/graph/badge.svg?token=CZBHY8J802)](https://codecov.io/gh/morfeojs/morfeo)
+[![Codecov](https://github.com/morfeojs/morfeo/actions/workflows/codecov.yml/badge.svg)](https://github.com/morfeojs/morfeo/actions/workflows/codecov.yml)
+[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
+[![GitHub license](https://img.shields.io/github/license/morfeojs/morfeo)](https://github.com/morfeojs/morfeo/blob/main/LICENSE)
+[![Contributing](https://img.shields.io/badge/PRs-welcome-brightgreen)](https://github.com/morfeojs/morfeo/blob/main/CONTRIBUTING.md)
+[![Netlify Status](https://api.netlify.com/api/v1/badges/93b009d2-94be-4d40-baa3-9f86a51922ce/deploy-status)](https://app.netlify.com/sites/cocky-kare-d8d81e/deploys)
+[![DeepScan grade](https://deepscan.io/api/teams/15451/projects/18608/branches/460695/badge/grade.svg)](https://deepscan.io/dashboard#view=project&tid=15451&pid=18608&bid=460695)
+
+---
 
 This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
 
 ## Installation
 
+From the root of the project (one folder above this one), run:
+
 ```console
-yarn install
+yarn init:docs
 ```
 
+### ⚠️ Warning
+
+If you run `yarn` directly in this folder you'll install the published version of the internal `@morfeo` packages,
+this means that you'll not be able to see your changes in case you made updates in one o more packages.
+By running `yarn init:docs` instead, the internal `@morfeo` packages will be symlinked to reflect your changes.
+
 ## Local Development
 
 ```console
 yarn start
+# Or, from the root of this project (one folder above this one)
+yarn start:docs
 ```
 
 This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
@@ -21,13 +48,3 @@ This command starts a local development server and opens up a browser window. Mo
 ```console
 yarn build
 ```
-
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
-
-## Deployment
-
-```console
-GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
-```
-
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/docs/Features/CLI/cli.mdx

@@ -6,7 +6,7 @@ description: Features > CLI > Introduction
 ---
 
 :::warning
-**@morfeo/cli** it's still in beta and will be ready soon.
+**@morfeo/cli** it's still in development and will be ready as soon as possible.
 :::
 
 If you don't need to generate styles `run time` or you don't want to use `javascript` at all, but you still want to benefit the morfeo eco-system and a centralized theme,

docs/docusaurus.config.js

@@ -18,7 +18,7 @@ module.exports = {
       title: '',
       logo: {
         alt: 'Morfeo Logo',
-        src: 'img/logo.svg',
+        src: 'img/logo-beta.svg',
       },
       items: [
         {

docs/package.json

@@ -14,10 +14,10 @@
     "write-heading-ids": "docusaurus write-heading-ids"
   },
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.15",
-    "@docusaurus/preset-classic": "2.0.0-beta.15",
-    "@docusaurus/theme-live-codeblock": "2.0.0-beta.15",
-    "@docusaurus/theme-search-algolia": "2.0.0-beta.15",
+    "@docusaurus/core": "^2.0.0-beta.18",
+    "@docusaurus/preset-classic": "^2.0.0-beta.18",
+    "@docusaurus/theme-live-codeblock": "^2.0.0-beta.18",
+    "@docusaurus/theme-search-algolia": "^2.0.0-beta.18",
     "@mdx-js/react": "^1.6.21",
     "@morfeo/dev-tools": "^0.5.0",
     "@morfeo/preset-default": "^0.5.0",

docs/sidebars.js

@@ -24,7 +24,7 @@ module.exports = {
         'Features/easy-to-test',
         {
           type: 'category',
-          label: '🔨 CLI (Beta)',
+          label: '🔨 CLI (Alpha)',
           collapsed: false,
           items: [
             'Features/CLI/morfeo-cli-introduction',

docs/src/components/HomePageHeader/HomePageHeader.js

@@ -27,8 +27,8 @@ export function HomepageHeader() {
               },
             ]}
           >
-            Morfeo is a tool to build design systems based on a theme. It
-            helps you to <i>follow a design language</i> and write{' '}
+            Morfeo is a tool to build design systems based on a theme. It helps
+            you to <i>follow a design language</i> and write{' '}
             <i>consistent UIs</i>, whatever it is the framework of your choice.
             It's easy to use and, with the
             <a href="/docs/Features/web-extension">

docs/src/components/HomepageFeatures/HomepageFeatures.js

@@ -31,7 +31,7 @@ const features = [
     text: 'CLI',
     link: '/docs/Features/CLI/',
     icon: <Icon name="cli" />,
-    badge: 'beta',
+    badge: 'alpha',
   },
 ];
 

docs/src/theme/Root.js

@@ -1,5 +1,4 @@
 import React from 'react';
-import Link from '@docusaurus/Link';
 import { morfeo, loadFont } from '@morfeo/react';
 import { initPreset } from '@morfeo/preset-default';
 import { enableMorfeoDevTool } from '@morfeo/dev-tools';
@@ -8,8 +7,6 @@ import { CookieProvider } from '../components/CookieBanner/CookieProvider';
 
 initPreset();
 
-const buttonStyle = morfeo.resolve({ corner: 'm' });
-
 fonts.forEach(font => loadFont(font));
 
 enableMorfeoDevTool();