Add Webpack page

This commit is contained in:
Jeremy Thomas 2018-07-14 18:38:27 +01:00
parent 0efd856f52
commit 884d887f44
15 changed files with 482 additions and 44 deletions

View File

@ -80,6 +80,51 @@
"icon": "plus",
"path": "/documentation/overview/mixins"
},
"customize": {
"name": "Customize",
"subtitle": "Create your <strong>own theme</strong> with a simple set of <strong>variables</strong>",
"color": "star",
"icon": "paint-brush",
"path": "/documentation/customize"
},
"customize-concepts": {
"name": "Concepts",
"subtitle": "What makes Bulma <strong>customizable</strong>",
"color": "info",
"icon": "lightbulb",
"path": "/documentation/customize/concepts"
},
"customize-variables": {
"name": "Variables",
"subtitle": "See how Bulma uses <strong>Sass variables</strong> to allow easy customization",
"color": "grey",
"icon": "cogs",
"path": "/documentation/customize/variables"
},
"customize-node-sass": {
"name": "With node-sass",
"subtitle": "Use npm/yarn and node-sass",
"color": "danger",
"icon_brand": "true",
"icon": "npm",
"path": "/documentation/customize/with-node-sass"
},
"customize-sass-cli": {
"name": "With Sass CLI",
"subtitle": "Use the Sass command line",
"color": "purple",
"icon_brand": "true",
"icon": "sass",
"path": "/documentation/customize/with-sass-cli"
},
"customize-webpack": {
"name": "With Webpack",
"subtitle": "Use Bulma with Webpack",
"color": "warning",
"icon_brand": "true",
"icon": "js",
"path": "/documentation/customize/with-webpack"
},
"modifiers": {
"name": "Modifiers",
"subtitle": "An <strong>easy-to-read</strong> naming system designed for humans",
@ -506,7 +551,8 @@
"extensions"
],
"categories": {
"overview": ["overview-start", "overview-customize", "overview-classes", "overview-modular", "overview-responsiveness", "overview-variables", "overview-colors", "overview-functions", "overview-mixins"],
"overview": ["overview-start", "overview-classes", "overview-modular", "overview-responsiveness", "overview-colors", "overview-functions", "overview-mixins"],
"customize": ["customize-concepts", "customize-variables", "customize-node-sass", "customize-sass-cli", "customize-webpack"],
"modifiers": ["modifiers-syntax", "modifiers-helpers", "modifiers-responsive-helpers", "modifiers-color-helpers", "modifiers-typography-helpers"],
"columns": ["columns-basics", "columns-sizes", "columns-responsiveness", "columns-nesting", "columns-gap", "columns-options"],
"layout": ["layout-container", "layout-level", "layout-media", "layout-hero", "layout-section", "layout-footer", "layout-tiles"],

View File

@ -4,7 +4,6 @@
{% assign category_links = category[1] %}
{% assign category_link = site.data.links.by_id[category_id] %}
{% if category_link.name != 'Customize' %}
<div class="bd-category {% if category_id == current_category %}is-active{% endif %}">
<header class="bd-category-header">
<a class="bd-category-toggle">
@ -33,7 +32,6 @@
{% endfor %}
</ul>
</div>
{% endif %}
{% endfor %}
</nav>

View File

@ -1,4 +1,4 @@
{% assign customize_link = site.data.links.by_id['overview-customize'] %}
{% assign customize_link = site.data.links.by_id['customize'] %}
<section id="customize" class="bd-easy section is-medium">
<div class="container">

View File

@ -22,4 +22,4 @@ $input-border-color: transparent;
$input-shadow: none;
// Import the rest of Bulma
@import "../bulma";
@import "../path/to/bulma";

View File

@ -49,9 +49,15 @@ $input-shadow: none;
</div>
<div class="content">
<p>
Since you are watching for changes, simply <strong>save the file</strong> to see the result:
</p>
{% if include.build %}
<p>
Rebuild the CSS to see the result:
</p>
{% else %}
<p>
Since you are watching for changes, simply <strong>save the file</strong> to see the result:
</p>
{% endif %}
</div>
{%

View File

@ -9,7 +9,7 @@
<div class="content">
<p>
Save this file as <code>mypage.html</code>.
Save this file as <code>mypage.html</code>{% if include.dist == true %} in the <code>dist</code> folder{% endif %}.
</p>
<p>
Notice the <code>css/mystyles.css</code> path for your stylesheet. This will be the location of the CSS file we will generate with Sass.

View File

@ -0,0 +1,26 @@
{% capture init %}
npm init
{% endcapture %}
{% capture step_1 %}
<div class="content">
<p>
In your terminal, create a new folder called <code>mybulma</code>, navigate to it, then type the following command:
</p>
</div>
{% highlight bash %}{{ init }}{% endhighlight %}
<div class="content">
<p>
This will launch an interactive setup to create <code>package.json</code>. When prompted for an <strong>entry point</strong>, enter <code>{{ include.entry }}</code>.
</p>
</div>
{% endcapture %}
{% assign step_title = '. Create a <code style="white-space: nowrap;">package.json</code> file' | prepend: include.number %}
{% include components/step.html
title=step_title
content=step_1
%}

View File

@ -1,6 +1,6 @@
{% capture scss_bulma %}
@charset "utf-8";
@import "{{ include.path }}/bulma/bulma.sass";
@import "{{ include.path }}";
{% endcapture %}
{% capture step_3 %}
@ -19,9 +19,32 @@
</div>
{% endcapture %}
{% capture step_3_bis %}
<div class="content">
<p>
Inside the same <code>src</code> folder, add a file called <code>mystyles.scss</code>:
</p>
</div>
{% highlight scss %}{{ scss_bulma }}{% endhighlight %}
<div class="content">
<p>
Make sure to write the correct path to the <code>bulma</code> folder.
</p>
</div>
{% endcapture %}
{% assign step_title = ". Create a Sass file" | prepend: include.number %}
{% include components/step.html
title=step_title
content=step_3
%}
{% if include.bis == true %}
{% include components/step.html
title=step_title
content=step_3_bis
%}
{% else %}
{% include components/step.html
title=step_title
content=step_3
%}
{% endif %}

View File

@ -10,21 +10,26 @@ breadcrumb:
- customize-concepts
---
{% assign variables_link = site.data.links.by_id['customize-node-sass'] %}
<div class="content">
<p>
Bulma is highly customizable thanks to <strong>415 Sass variables</strong> living across <strong>28 files</strong>.
</p>
<p>
These variables exist at 3 levels:
These variables exist at 4 levels:
</p>
<ul>
<li>
<strong><a href="/documentation/overview/variables/#initial-variables">initial variables</a></strong>: global variables with <strong>literal</strong> values
<strong><a href="{{ site.url }}{{ variables_link.path }}#initial-variables">initial variables</a></strong>: global variables with <strong>literal</strong> values
</li>
<li>
<strong><a href="/documentation/overview/variables/#derived-variables">derived variables</a></strong>: global variables with values that reference other variables, or are computed
<strong><a href="{{ site.url }}{{ variables_link.path }}#derived-variables">derived variables</a></strong>: global variables with values that reference other variables, or are computed
</li>
<li>
<strong><a href="{{ site.url }}{{ variables_link.path }}#generic-variables">generic variables</a></strong>: for the HTML elements which carry no CSS class
</li>
<li>
<strong>element/component variables</strong>: variables that are specific to a Bulma element/component
@ -38,6 +43,10 @@ breadcrumb:
{% include elements/anchor.html name="Strategy" %}
{% assign node_sass_link = site.data.links.by_id['customize-node-sass'] %}
{% assign sass_cli_link = site.data.links.by_id['customize-sass-cli'] %}
{% assign webpack_link = site.data.links.by_id['customize-webpack'] %}
<div class="content">
<p>
To customize Bulma, you will need to:
@ -54,4 +63,20 @@ breadcrumb:
create your own <code>.scss</code> or <code>.sass</code> file
</li>
</ul>
<p>
This can be achieved with:
</p>
<ul>
<li>
with <a href="{{ site.url }}{{ node_sass_link.path }}">node-sass</a>
</li>
<li>
with the <a href="{{ site.url }}{{ sass_cli_link.path }}">Sass CLI</a>
</li>
<li>
with <a href="{{ site.url }}{{ webpack_link.path }}">Webpack</a>
</li>
</ul>
</div>

View File

@ -0,0 +1,107 @@
---
title: Variables
layout: documentation
doc-tab: customize
doc-subtab: variables
breadcrumb:
- home
- documentation
- customize
- customize-variables
---
{% assign initial_variables = site.data.variables.utilities.initial-variables %}
{% assign initial_vars = initial_variables.by_name %}
{% assign derived_variables = site.data.variables.utilities.derived-variables %}
{% assign derived_vars = derived_variables.by_name %}
<div class="content">
<p>Bulma has <strong>two</strong> variable files divided into <strong>4</strong> sections:</p>
<ol>
<li>
<strong>Initial variables</strong>: where you define variables by <strong>literal value</strong>, like:
<ul>
<li><strong>colors</strong>: <code>{{ initial_vars['$blue'].name }}: {{ initial_vars['$blue'].value }}</code></li>
<li><strong>font sizes</strong>: <code>{{ initial_vars['$size-1'].name }}: {{ initial_vars['$size-1'].value }}</code></li>
<li><strong>dimensions</strong>: <code>{{ initial_vars['$gap'].name }}: {{ initial_vars['$gap'].value }}</code></li>
<li><strong>other values</strong>: <code>{{ initial_vars['$easing'].name }}: {{ initial_vars['$easing'].value }}</code> or <code>{{ initial_vars['$radius-large'].name }}: {{ initial_vars['$radius-large'].value }}</code></li>
</ul>
</li>
<li>
<strong>Derived variables</strong> where variables are <strong>calculated</strong> from the values set in the previous file. For example, you can have:
<ul>
<li>
<strong>Primary colors</strong> derived from the initial variables:
<ul>
<li><code>{{ derived_vars['$primary'].name }}: {{ derived_vars['$primary'].value }}</code></li>
<li><code>{{ derived_vars['$link'].name }}: {{ derived_vars['$link'].value }}</code></li>
<li><code>{{ derived_vars['$info'].name }}: {{ derived_vars['$info'].value }}</code></li>
<li><code>{{ derived_vars['$success'].name }}: {{ derived_vars['$success'].value }}</code></li>
<li><code>{{ derived_vars['$warning'].name }}: {{ derived_vars['$warning'].value }}</code></li>
<li><code>{{ derived_vars['$danger'].name }}: {{ derived_vars['$danger'].value }}</code></li>
<li><code>{{ derived_vars['$dark'].name }}: {{ derived_vars['$dark'].value }}</code></li>
<li><code>{{ derived_vars['$text'].name }}: {{ derived_vars['$text'].value }}</code></li>
</ul>
</li>
<li><code>{{ derived_vars['$background'].name }}: {{ derived_vars['$background'].value }}</code>: a general background color</li>
<li><code>{{ derived_vars['$link'].name }}: {{ derived_vars['$link'].value }}</code>: the links use the primary color</li>
<li><code>{{ derived_vars['$family-primary'].name }}: {{ derived_vars['$family-primary'].value }}</code>: the primary font family is the sans-serif one</li>
<li>
<strong>Lists and maps</strong> which are collections of already defined variables:
<ul>
<li><code>{{ derived_vars['$colors'].name }}: {{ derived_vars['$colors'].value }}</code></li>
<li><code>{{ derived_vars['$shades'].name }}: {{ derived_vars['$shades'].value }}</code></li>
<li><code>{{ derived_vars['$sizes'].name }}: {{ derived_vars['$sizes'].value }}</code></li>
</ul>
</li>
</ul>
</li>
</ol>
<p>
To <strong>override</strong> any of these variables, just set them <em>before</em> importing Bulma.
</p>
</div>
{% include elements/anchor.html name="Initial variables" %}
<div class="content">
<p>
These are <a href="https://github.com/jgthms/bulma/blob/master/sass/{{ initial_variables.file_path }}" target="_blank" rel="nofollow">initial variables</a> with a <strong>literal</strong> value.
</p>
</div>
<table class="table is-bordered">
<tbody>
{% for variable_name in initial_variables.list %}
{% assign variable = initial_vars[variable_name] %}
{% include elements/variable-row.html variable=variable hide_computed =true%}
{% endfor %}
<tbody>
</table>
{% capture custom_message %}
These are <a href="https://github.com/jgthms/bulma/blob/master/sass/{{ derived_variables.file_path }}" target="_blank" rel="nofollow">variables</a> with a value that <strong>references</strong> another variable.
{% endcapture %}
{%
include elements/variables.html
anchor_name = 'Derived variables'
data = derived_variables
custom_message = custom_message
table_class = 'is-bordered'
%}
{% capture custom_message %}
You can use the following <a href="{{ site.data.variables.base.generic.file_url }}" target="_blank">generic variables</a> for general <strong>customization</strong>. Simply set one or multiple of these variables <em>before</em> importing Bulma. <a href="{{ site.url }}/documentation/overview/customize/">Learn how</a>.
{% endcapture %}
{%
include elements/variables.html
anchor_name = 'Generic variables'
tab = 'base'
subtab = 'generic'
custom_message = custom_message
table_class = 'is-bordered'
%}

View File

@ -10,26 +10,6 @@ breadcrumb:
- customize-node-sass
---
{% capture init %}
npm init
{% endcapture %}
{% capture step_1 %}
<div class="content">
<p>
In your terminal, create a new folder called <code>mybulma</code>, navigate to it, then type the following command:
</p>
</div>
{% highlight bash %}{{ init }}{% endhighlight %}
<div class="content">
<p>
This will launch an interactive setup to create <code>package.json</code>. When prompted for an <strong>entry point</strong>, enter <code>sass/mystyles.scss</code>.
</p>
</div>
{% endcapture %}
{% capture dependencies %}
npm install node-sass --save-dev
npm install bulma --save-dev
@ -112,10 +92,10 @@ npm start
<p>
To test it out, go in your <strong>terminal</strong> and run the following command:
</p>
{% highlight bash %}{{ npm_build }}{% endhighlight %}
</div>
{% highlight bash %}{{ npm_build }}{% endhighlight %}
<div class="content">
<p>
If set up correctly, you will see the following message:
@ -149,9 +129,9 @@ npm start
{% highlight bash %}{{ npm_watch }}{% endhighlight %}
{% endcapture %}
{% include components/step.html
title='1. Create a <code style="white-space: nowrap;">package.json</code> file'
content=step_1
{% include steps/create-package.html
number="1"
entry="sass/mystyles.scss"
%}
<hr>
@ -165,7 +145,7 @@ npm start
{% include steps/create-sass-file.html
number="3"
path="../node_modules"
path="../node_modules/bulma/bulma.sass"
%}
<hr>

View File

@ -119,7 +119,7 @@ sass --watch --sourcemap=none sass/mystyles.scss:css/mystyles.css
<hr>
{% assign bulma_path = site.data.meta.version | prepend: "../bulma-" %}
{% assign bulma_path = site.data.meta.version | prepend: "../bulma-" | append: "/bulma/bulma.sass" %}
{% include steps/create-sass-file.html
number="3"

View File

@ -0,0 +1,223 @@
---
title: With webpack
layout: documentation
doc-tab: customize
doc-subtab: webpack
breadcrumb:
- home
- documentation
- customize
- customize-webpack
---
{% capture dependencies %}
npm install bulma --save-dev
npm install css-loader --save-dev
npm install extract-text-webpack-plugin@next --save-dev
npm install node-sass --save-dev
npm install sass-loader --save-dev
npm install style-loader --save-dev
npm install webpack --save-dev
npm install webpack-cli --save-dev
{% endcapture %}
{% capture package %}
{
"name": "mybulma",
"version": "1.0.0",
"main": "webpack.config.js",
"license": "MIT",
"devDependencies": {
"bulma": "^0.7.1",
"css-loader": "^1.0.0",
"extract-text-webpack-plugin": "^4.0.0-beta.0",
"node-sass": "^4.9.2",
"sass-loader": "^7.0.3",
"style-loader": "^0.21.0",
"webpack": "^4.16.0",
"webpack-cli": "^3.0.8"
}
}
{% endcapture %}
{% capture step_2 %}
<div class="content">
<p>
Install the packages required to parse and build your CSS:
</p>
</div>
{% highlight bash %}{{ dependencies }}{% endhighlight %}
<div class="content">
<p>
Your <code>package.json</code> should look like this at this point.
</p>
</div>
{% highlight bash %}{{ package }}{% endhighlight %}
{% endcapture %}
{% capture config %}
const path = require('path');
const ExtractTextPlugin = require("extract-text-webpack-plugin");
module.exports = {
entry: './src/index.js',
output: {
path: path.resolve(__dirname, 'dist'),
filename: 'js/bundle.js'
},
module: {
rules: [{
test: /\.scss$/,
use: ExtractTextPlugin.extract({
fallback: 'style-loader',
use: [
'css-loader',
'sass-loader'
]
})
}]
},
plugins: [
new ExtractTextPlugin('css/mystyles.css'),
]
};
{% endcapture %}
{% capture step_3 %}
<div class="content">
<p>
Create a <code>webpack.config.js</code> file:
</p>
</div>
<div class="highlight-full">
{% highlight js %}{{ config }}{% endhighlight %}
</div>
<div class="content">
<p>
This setup takes the <code>src</code> folder as input, and outputs in the <code>dist</code> folder.
</p>
</div>
{% endcapture %}
{% capture require_css %}
require('./mystyles.scss');
{% endcapture %}
{% capture step_4 %}
<div class="content">
<p>
Create a <code>src</code> folder in which you add a file called <code>index.js</code> with the following content:
</p>
</div>
{% highlight js %}{{ require_css }}{% endhighlight %}
{% endcapture %}
{% capture step_6 %}
<div class="content">
<p>
Create a <code>dist</code> folder in which you add a <code>css</code> folder, and a <code>js</code> folder. Leave these last two folders empty. Their content will be generated by the webpack build.
</p>
</div>
{% endcapture %}
{% capture webpack_script %}
"scripts": {
"build": "webpack --mode production"
},
{% endcapture %}
{% capture npm_build %}
npm run build
{% endcapture %}
{% capture npm_build_success %}
Rendering Complete, saving .css file...
Wrote CSS to /path/to/mybulma/css/mystyles.css
{% endcapture %}
{% capture step_8 %}
<div class="content">
<p>
In <code>package.json</code>, add the following:
</p>
</div>
{% highlight html %}{{ webpack_script }}{% endhighlight %}
<div class="content">
<p>
To test it out, go in your <strong>terminal</strong> and run the following command:
</p>
</div>
{% highlight bash %}{{ npm_build }}{% endhighlight %}
{% endcapture %}
{% include steps/create-package.html
number="1"
entry="webpack.config.js"
%}
<hr>
{% include components/step.html
title="2. Install the dev dependencies"
content=step_2
%}
<hr>
{% include components/step.html
title="3. Create a webpack config"
content=step_3
%}
<hr>
{% include components/step.html
title="4. Create a <code>src</code> folder"
content=step_4
%}
<hr>
{% include steps/create-sass-file.html
number="5"
path='~bulma/bulma'
bis=true
%}
<hr>
{% include components/step.html
title="6. Create a <code>dist</code> folder"
content=step_6
%}
<hr>
{% include steps/create-html-page.html
number="7"
dist=true
%}
<hr>
{% include components/step.html
title="8. Add node scripts to build your bundle"
content=step_8
%}
<hr>
{% include steps/add-custom-styles.html
number="9"
build=true
%}

View File

@ -10,6 +10,8 @@ breadcrumb:
- overview-customize
---
<meta http-equiv="refresh" content="0; url={{ site.url }}/documentation/customize/">
{% capture scss_code %}
// 1. Import the initial variables
@import "../sass/utilities/initial-variables";

View File

@ -10,6 +10,8 @@ breadcrumb:
- overview-variables
---
<meta http-equiv="refresh" content="0; url={{ site.url }}/documentation/customize/variables/">
{% assign initial_variables = site.data.variables.utilities.initial-variables %}
{% assign initial_vars = initial_variables.by_name %}
{% assign derived_variables = site.data.variables.utilities.derived-variables %}