feat: improved documentation (#18)

This adds documentation with Docusaurus which is to be published to
GitHub Pages.

.github/workflows/deploy-docs.yml

@@ -0,0 +1,42 @@
+name: Deploy to GitHub Pages
+
+defaults:
+  run:
+    working-directory: documentation
+
+on:
+  push:
+    branches:
+      - master
+    # Review gh actions docs if you want to further define triggers, paths, etc
+    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
+    paths:
+      - documentation
+
+jobs:
+  deploy:
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+      - name: Build website
+        run: npm run build
+
+      # Popular action to deploy to GitHub Pages:
+      # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          # Build output to publish to the `gh-pages` branch:
+          publish_dir: ./documentation/build
+          # The following lines assign commit authorship to the official
+          # GH-Actions bot for deploys to `gh-pages` branch:
+          # https://github.com/actions/checkout/issues/13#issuecomment-724415212

.github/workflows/test-deploy-docs.yml

@@ -0,0 +1,30 @@
+name: Test GitHub Pages deployment
+
+defaults:
+  run:
+    working-directory: documentation
+
+on:
+  pull_request:
+    branches:
+      - master
+    # Review gh actions docs if you want to further define triggers, paths, etc
+    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
+    paths:
+      - documentation
+
+jobs:
+  test-deploy:
+    name: Test deployment
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+      - name: Test build website
+        run: npm run build

.github/workflows/test.yml

@@ -0,0 +1,37 @@
+name: Test
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+      - name: Run testbuild
+        run: npm run testbuild
+      - name: Run tests
+        run: npm run test:ci
+
+      - name: Publish test results
+        uses: mikepenz/action-junit-report@v3
+        if: success() || failure()
+        with:
+          include_passed: true
+          fail_on_failure: true
+          require_tests: true
+          report_paths: "junit.xml"
+          detailed_summary: true

README.md

@@ -1,44 +1,45 @@
-# css-fx-layout
+# css-fx-layout 📚
 
-[![CircleCI](https://circleci.com/gh/philmtd/css-fx-layout/tree/master.svg?style=svg)](https://circleci.com/gh/philmtd/css-fx-layout/tree/master)
+![GitHub Actions Test](https://github.com/philmtd/css-fx-layout/actions/workflows/test.yml/badge.svg)
 [![npm version](https://badge.fury.io/js/css-fx-layout.svg)](https://www.npmjs.com/package/css-fx-layout)
 
-This is a lightweight SCSS flexbox library. It is inspired by Angular's [Flex-Layout](https://github.com/angular/flex-layout) and can replace the
+This is a lightweight and modular SCSS flexbox library. It is inspired by Angular's [Flex-Layout](https://github.com/angular/flex-layout) and can replace the
 most popular functions of the (by now deprecated) Angular library.
 
 ## Features
 
 This library gives you the option between using CSS classes or data-attributes. Both options give you the same features but the CSS classes can be more verbose when you want a more complex layout.
-Check out the [Wiki](https://github.com/philmtd/css-fx-layout/wiki) for a detailed documentation.
 
-### CSS class selectors
-
-Using the CSS classes is more verbose but the recommended way to use this library:
-
-* `.fx-layout-` and `.fx-align-`: CSS classes to control the flexbox container
-* `.fx-gap--`: CSS classes to add gaps between the elements in a flex container
-* `.show-` and `.hide-`: CSS classes which can be used to show/hide elements depending on the screen size
-* `.fx-flex` and `.fx-glex-grow`: Classes to control flex behaviour of an element
+**Please refer to the documentation on [https://philmtd.github.io/css-fx-layout](https://philmtd.github.io/css-fx-layout) for a full list of all available selectors and features.**
 
 ### HTML data-attribute selectors
 
 Using the data attributes is the easiest way to use this library and easier to migrate to from Angular Flex-Layout:
 
-* `data-layout` and `data-layout-align`: HTML attributes to be used to control the flexbox container
-* `data-layout-gap`: attribute to add gaps between the elements in a flex container
-* `data-hide-` and `data-show-`: attributes which can be used to show/hide elements depending on the screen size
-* `data-fx-flex` and `data-fx-flex-grow`: Control flex behaviour of an element
+For example css-fx-layout provides attributes like the following, which can be configured through the values passed to them:
+
+* `data-layout` and `data-layout-align`
+* `data-layout-gap`
+* `data-hide-...` and `data-show-...`
+* `data-fx-flex`
+
+### CSS class selectors
+
+Using the CSS classes is more verbose and the more "CSS-y" way of styling your HTML:
+
+For example css-fx-layout provides classes with naming patterns like:
+
+* `fx-layout-...` and `fx-align-...`
+* `fx-gap-...`
+* `show-...` and `hide-...`
+* `fx-flex-...`
 
 ### Responsive API
 
 The library provides a responsive API which allows to create different layouts for different screen sizes using known breakpoints
-like `xs`, `sm`, `md`, `lg`, `xl` and including `lt-` and `gt-` variations of them. Please check out the [Wiki](https://github.com/philmtd/css-fx-layout/wiki)
+like `xs`, `sm`, `md`, `lg`, `xl` and including `lt-` and `gt-` variations of them. Please check out the [documentation](https://philmtd.github.io/css-fx-layout/docs/responsive)
 for details on how to use it.
 
-### SCSS Mixins
-
-All functionality is also available as mixins to accompany this library or to create your own customized selectors.
-
 ## Getting started
 
 Add the library to your project's `package.json`:
@@ -47,46 +48,7 @@ Add the library to your project's `package.json`:
 npm i -s css-fx-layout
 ```
 
-Then use the provided mixins in your main stylesheet to include the css-fx-layout selectors. You can choose between using CSS classes
-or HTML data attributes (or, while not recommended, use both). If you want to use the layout-gap functionality you can customise which selectors
-are going to be generated by providing the start, end and unit as shown in the example below.
-
-<table>
-<tr>
-<th>CSS Classes</th>
-<th>HTML Data Attributes</th>
-</tr>
-<tr>
-<td>
-
-````scss
-@use "css-fx-layout" as fx;
-
-// If you want to include the responsive API selectors
-$includeResponsiveApi: true;
-
-// If you choose to use CSS class selectors:
-@include fx.class-selectors($includeResponsiveApi);
-@include fx.gap-class-selectors(1, 16, px em, $includeResponsiveApi);
-````
-
-</td>     
-<td>   
-
-````scss
-@use "css-fx-layout" as fx;
-
-// If you want to include the responsive API selectors
-$includeResponsiveApi: true;
-
-// If you choose to use attribute selectors:
-@include fx.attribute-selectors($includeResponsiveApi);
-@include fx.gap-attribute-selectors(1, 16, px em, $includeResponsiveApi);
-````
-
-</td>
-</tr>
-</table>
+Then follow the [Getting Started](https://philmtd.github.io/css-fx-layout/docs/getting-started) guide in the documentation.
 
 ## Examples
 
@@ -130,7 +92,7 @@ This is the simplest example. It will make the div a flex container and align th
 
 The resulting layout:
 
-<img src="./docs/example-1.png" alt="Example 1" width="280px" />
+<img src="images/example-1.png" alt="Example 1" width="280px" />
 
 
 #### Example 2
@@ -175,7 +137,7 @@ An advanced example that aligns the items in reverse order with a gap of four pi
 
 The resulting layout:
 
-<img src="./docs/example-2.png" alt="Example 2" width="280px" />
+<img src="images/example-2.png" alt="Example 2" width="280px" />
 
 #### Example 3
 Vertically and horizontally center an element in its parent.
@@ -212,7 +174,7 @@ Vertically and horizontally center an element in its parent.
 
 The resulting layout:
 
-<img src="./docs/example-3.png" alt="Example 3" width="280px" />
+<img src="images/example-3.png" alt="Example 3" width="280px" />
 
 ### Show/Hide
 
@@ -249,11 +211,6 @@ This will hide the first span on `sm` sized screens and show the second span onl
 </td>
 </tr>
 </table>
-
-### Compiled CSS
-There are no pre-compiled CSS files available for css-fx-layout 2 and above.
-Version 1 releases provided minified pre-compiled CSS files. If you are interested in them you can find and download them from
-the [releases page](https://github.com/philmtd/css-fx-layout/releases/).
 
 ## What problem does this library solve?
 

documentation/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

documentation/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> 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.

documentation/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

documentation/blog/authors.yml

@@ -0,0 +1,5 @@
+philmtd:
+  name: Philip Dakowitz
+  title: Maintainer of css-fx-layout
+  url: https://github.com/philmtd
+  image_url: https://github.com/philmtd.png