Merge pull request #808 from mpourismaiel/docs/postcss/create

Document postcss configurations and remove purgecss

Author: stp-ip

exampleSite/config-dev.toml

@@ -15,9 +15,6 @@ CanonifyURLs = true
 # Google Analytics tracking
 googleAnalytics = ""
 
-[build]
-  writeStats = true
-
 [outputs]
   home = ["HTML", "JSON"]
 

exampleSite/content/docs/global-variables/content.md

@@ -28,7 +28,7 @@ Set the background of the fragment.
 Background also affects the text color of the fragment's content.
 For the background colors of `white`, `light`, `secondary` and `primary` we use Bootstrap's `text_dark` class on content and for other backgrounds, we use `text_light`.
 
-List of all supported colors can be found in [supported colors]({{< ref "supported-colors" >}}) section of the docs.
+List of all supported colors can be found in [supported colors]({{< ref "styling" >}}#supported-colors) section of the docs.
 
 #### title
 *type: string*

exampleSite/content/docs/styling/content.md

@@ -0,0 +1,87 @@
++++
+fragment = "content"
+weight = 100
+
+title = "Supported Colors"
+
+[sidebar]
+  sticky = true
++++
+
+### Supported Colors
+
+Fragments and various elements can be customized further using Bootstrap color classes.
+These colors are customized within `config.toml` to fit the Syna theme.
+
+| class     | colors  |
+| --------- | ------- |
+| primary   | #00838F |
+| secondary | #868e96 |
+| success   | #008f54 |
+| info      | #00838F |
+| warning   | #fdf314 |
+| danger    | #dc1200 |
+| light     | #f8f9fa |
+| dark      | #343a40 |
+
+In order to change the primary color, you can update the primary color within your `config.toml` file:
+
+```toml
+[params]
+  [params.colors]
+      primary = "#00838F"
+```
+
+Please note that `colors` is under `params` section of your configuration.
+
+These colors are mainly used for backgrounds and button colors.  
+By changing the colors, all fragment colors and backgrounds will be changed to the new colors. Links, inline code and other elements will also be changed.  
+These colors can also be overwritten for more details see our [style documentation]({{< ref "development" >}}#styles).
+
+**Important:** These colors define the color scheme that Bootstrap uses. As you update them, be careful to keep the contrast between different colors. Since it's not possible to recognize the contrast of colors within Syna, we rely on the names of colors when setting different text colors for different backgrounds. So if you change the `primary` color to a darker color, text colors will still use the `text-body` class from Bootstrap which is a dark color and may result in unreadable text.
+
+### PostCSS
+
+PostCSS is enabled by default and will look for its configuration file when Hugo is building your website. You can add your configuration to `postcss.config.js` at the root of your project. Here are some recommended configurations. Please note that you can combine these configurations and use them together.
+
+#### Removing unused CSS
+
+We recommend using `@fullhuman/postcss-purgecss` along PostCSS to remove unused CSS from your website. PurgeCSS will drastically reduce the size of your website. Since we use Bootstrap to develop our built-in fragments, the final CSS bundle is mostly Bootstrap code that goes unused. To remove the unused parts, please run:
+
+- `npm install @fullhuman/postcss-purgecss` or `yarn add @fullhuman/postcss-purgecss`
+- Add the following code to `<root-directory>/postcss.config.js`:
+
+```javascript
+const purgecss = require('@fullhuman/postcss-purgecss')({
+  content: ['./hugo_stats.json'],
+  defaultExtractor: (content) => {
+    let els = JSON.parse(content).htmlElements;
+    return els.tags.concat(els.classes, els.ids, [
+      'active',
+      'show',
+      'in',
+    ]);
+  },
+});
+
+module.exports = {
+  plugins: [
+    ...(process.env.HUGO_ENVIRONMENT === 'production' ? [purgecss] : []),
+  ],
+};
+```
+
+### RTL stylesheet
+
+Syna is created for LTR languages but changing the theme to accommodate RTL languages is quite easy. In order to change the direction of the stylesheet, please run the following command:
+
+- `npm install rtlcss` or `yarn add rtlcss`
+- Add the following code to `<root-directory>/postcss.config.js`:
+
+```javascript
+module.exports = {
+  plugins: [
+    require('rtlcss')()
+  ]
+}
+```

exampleSite/content/docs/styling/index.md

@@ -0,0 +1,4 @@
++++
+title = "Styling"
+weight = 40
++++

exampleSite/content/docs/supported-colors/content.md

@@ -25,7 +25,6 @@
     "webpack-cli": "^3.0.8"
   },
   "dependencies": {
-    "@fullhuman/postcss-purgecss": "^2.3.0",
     "react": "^16.4.1",
     "react-dom": "^16.4.1"
   }

exampleSite/content/docs/supported-colors/index.md

@@ -2,14 +2,6 @@
 # yarn lockfile v1
 
 
-"@fullhuman/postcss-purgecss@^2.3.0":
-  version "2.3.0"
-  resolved "https://registry.yarnpkg.com/@fullhuman/postcss-purgecss/-/postcss-purgecss-2.3.0.tgz#50a954757ec78696615d3e118e3fee2d9291882e"
-  integrity sha512-qnKm5dIOyPGJ70kPZ5jiz0I9foVOic0j+cOzNDoo8KoCf6HjicIZ99UfO2OmE7vCYSKAAepEwJtNzpiiZAh9xw==
-  dependencies:
-    postcss "7.0.32"
-    purgecss "^2.3.0"
-
 "@webassemblyjs/ast@1.5.13":
   version "1.5.13"
   resolved "https://registry.yarnpkg.com/@webassemblyjs/ast/-/ast-1.5.13.tgz#81155a570bd5803a30ec31436bc2c9c0ede38f25"
@@ -1106,15 +1098,6 @@ chalk@^2.0.0, chalk@^2.0.1, chalk@^2.1.0, chalk@^2.3.2, chalk@^2.4.1:
     escape-string-regexp "^1.0.5"
     supports-color "^5.3.0"
 
-chalk@^2.4.2:
-  version "2.4.2"
-  resolved "https://registry.yarnpkg.com/chalk/-/chalk-2.4.2.tgz#cd42541677a54333cf541a49108c1432b44c9424"
-  integrity sha512-Mti+f9lpJNcwF4tWV8/OrTTtF1gZi+f8FqlyAdouralcFWFQWF2+NgCHShjkCb+IFBLq9buZwE1xckQU4peSuQ==
-  dependencies:
-    ansi-styles "^3.2.1"
-    escape-string-regexp "^1.0.5"
-    supports-color "^5.3.0"
-
 chardet@^0.5.0:
   version "0.5.0"
   resolved "https://registry.yarnpkg.com/chardet/-/chardet-0.5.0.tgz#fe3ac73c00c3d865ffcc02a0682e2c20b6a06029"
@@ -1230,11 +1213,6 @@ combined-stream@1.0.6, combined-stream@^1.0.5, combined-stream@~1.0.5:
   dependencies:
     delayed-stream "~1.0.0"
 
-commander@^5.0.0:
-  version "5.1.0"
-  resolved "https://registry.yarnpkg.com/commander/-/commander-5.1.0.tgz#46abbd1652f8e059bddaef99bbdcb2ad9cf179ae"
-  integrity sha512-P0CysNDQ7rtVw4QIQtm+MRxV66vKFSvlsQvGYXZWR3qFU0jlMKHZZZgw8e+8DSah4UDKMqnknRDQz+xuQXQ/Zg==
-
 commander@~2.13.0:
   version "2.13.0"
   resolved "https://registry.yarnpkg.com/commander/-/commander-2.13.0.tgz#6964bca67685df7c1f1430c584f07d7597885b9c"
@@ -1409,11 +1387,6 @@ cssesc@^0.1.0:
   version "0.1.0"
   resolved "https://registry.yarnpkg.com/cssesc/-/cssesc-0.1.0.tgz#c814903e45623371a0477b40109aaafbeeaddbb4"
 
-cssesc@^3.0.0:
-  version "3.0.0"
-  resolved "https://registry.yarnpkg.com/cssesc/-/cssesc-3.0.0.tgz#37741919903b868565e1c09ea747445cd18983ee"
-  integrity sha512-/Tb/JcjK111nNScGob5MNtsntNM1aCNUDipB/TkwZFhyDrrE47SOx/18wF2bbjgc3ZzCSKW1T5nt5EbFoAz/Vg==
-
 currently-unhandled@^0.4.1:
   version "0.4.1"
   resolved "https://registry.yarnpkg.com/currently-unhandled/-/currently-unhandled-0.4.1.tgz#988df33feab191ef799a61369dd76c17adf957ea"
@@ -2173,11 +2146,6 @@ indent-string@^2.1.0:
   dependencies:
     repeating "^2.0.0"
 
-indexes-of@^1.0.1:
-  version "1.0.1"
-  resolved "https://registry.yarnpkg.com/indexes-of/-/indexes-of-1.0.1.tgz#f30f716c8e2bd346c7b67d3df3915566a7c05607"
-  integrity sha1-8w9xbI4r00bHtn0985FVZqfAVgc=
-
 indexof@0.0.1:
   version "0.0.1"
   resolved "https://registry.yarnpkg.com/indexof/-/indexof-0.0.1.tgz#82dc336d232b9062179d05ab3293a66059fd435d"
@@ -3216,28 +3184,10 @@ postcss-modules-values@^1.3.0:
     icss-replace-symbols "^1.1.0"
     postcss "^6.0.1"
 
-postcss-selector-parser@^6.0.2:
-  version "6.0.2"
-  resolved "https://registry.yarnpkg.com/postcss-selector-parser/-/postcss-selector-parser-6.0.2.tgz#934cf799d016c83411859e09dcecade01286ec5c"
-  integrity sha512-36P2QR59jDTOAiIkqEprfJDsoNrvwFei3eCqKd1Y0tUsBimsq39BLp7RD+JWny3WgB1zGhJX8XVePwm9k4wdBg==
-  dependencies:
-    cssesc "^3.0.0"
-    indexes-of "^1.0.1"
-    uniq "^1.0.1"
-
 postcss-value-parser@^3.3.0:
   version "3.3.0"
   resolved "https://registry.yarnpkg.com/postcss-value-parser/-/postcss-value-parser-3.3.0.tgz#87f38f9f18f774a4ab4c8a232f5c5ce8872a9d15"
 
-postcss@7.0.32:
-  version "7.0.32"
-  resolved "https://registry.yarnpkg.com/postcss/-/postcss-7.0.32.tgz#4310d6ee347053da3433db2be492883d62cec59d"
-  integrity sha512-03eXong5NLnNCD05xscnGKGDZ98CyzoqPSMjOe6SuoQY7Z2hIj0Ld1g/O/UQRuOle2aRtiIRDg9tDcTGAkLfKw==
-  dependencies:
-    chalk "^2.4.2"
-    source-map "^0.6.1"
-    supports-color "^6.1.0"
-
 postcss@^6.0.1, postcss@^6.0.23:
   version "6.0.23"
   resolved "https://registry.yarnpkg.com/postcss/-/postcss-6.0.23.tgz#61c82cc328ac60e677645f979054eb98bc0e3324"
@@ -3320,16 +3270,6 @@ punycode@^2.1.0:
   version "2.1.1"
   resolved "https://registry.yarnpkg.com/punycode/-/punycode-2.1.1.tgz#b58b010ac40c22c5657616c8d2c2c02c7bf479ec"
 
-purgecss@^2.3.0:
-  version "2.3.0"
-  resolved "https://registry.yarnpkg.com/purgecss/-/purgecss-2.3.0.tgz#5327587abf5795e6541517af8b190a6fb5488bb3"
-  integrity sha512-BE5CROfVGsx2XIhxGuZAT7rTH9lLeQx/6M0P7DTXQH4IUc3BBzs9JUzt4yzGf3JrH9enkeq6YJBe9CTtkm1WmQ==
-  dependencies:
-    commander "^5.0.0"
-    glob "^7.0.0"
-    postcss "7.0.32"
-    postcss-selector-parser "^6.0.2"
-
 qs@~6.4.0:
   version "6.4.0"
   resolved "https://registry.yarnpkg.com/qs/-/qs-6.4.0.tgz#13e26d28ad6b0ffaa91312cd3bf708ed351e7233"
@@ -3979,13 +3919,6 @@ supports-color@^5.3.0, supports-color@^5.4.0:
   dependencies:
     has-flag "^3.0.0"
 
-supports-color@^6.1.0:
-  version "6.1.0"
-  resolved "https://registry.yarnpkg.com/supports-color/-/supports-color-6.1.0.tgz#0764abc69c63d5ac842dd4867e8d025e880df8f3"
-  integrity sha512-qe1jfm1Mg7Nq/NSh6XE24gPXROEVsWHxC1LIx//XNlD9iw7YZQGjZNjYN7xGaEG6iKdA8EtNFW6R0gjnVXp+wQ==
-  dependencies:
-    has-flag "^3.0.0"
-
 tapable@^1.0.0:
   version "1.0.0"
   resolved "https://registry.yarnpkg.com/tapable/-/tapable-1.0.0.tgz#cbb639d9002eed9c6b5975eb20598d7936f1f9f2"
@@ -4142,11 +4075,6 @@ union-value@^1.0.0:
     is-extendable "^0.1.1"
     set-value "^0.4.3"
 
-uniq@^1.0.1:
-  version "1.0.1"
-  resolved "https://registry.yarnpkg.com/uniq/-/uniq-1.0.1.tgz#b31c5ae8254844a3a8281541ce2b04b865a734ff"
-  integrity sha1-sxxa6CVIRKOoKBVBzisEuGWnNP8=
-
 unique-filename@^1.1.0:
   version "1.1.0"
   resolved "https://registry.yarnpkg.com/unique-filename/-/unique-filename-1.1.0.tgz#d05f2fe4032560871f30e93cbe735eea201514f3"