A Git repo of a Middleman 4 project set up with Tailwind CSS and Webpack preconfigured. Which is great, because Webpack is kind of a bitch.
The webpack setup has all CSS being tree shaken (removing all unused CSS so that Tailwind isn't 400kb.) as well as minified. All Javascript is transpiled via Babel and of course minified. This is all done outside of Middleman's asset pipeline, so you probably don't want to mess around with that too too much.
On a different note, this package is definitely opinionated. I have installed all my favorite gems to get me building client websites as quickly as possible. It includes things such as image compression, sitemap building, easy svg tags, meta tags building among other helpers and tools.
If you don't want that and just want the webpack.config.js, feel free to rip it out.
Massive thanks to the work done by gabrielecanepa and his work on his middleman-webpack template. It was a major help putting together this project and wouldn't have been possible without his help.
Looking through arandilopez's repo for his personal site (https://github.com/arandilopez/arandilopez.me) was very helpful as well.
The following section is from the original middleman-webpack template repo mentioned above; some steps are helpful for setup.
This is a template for Middleman 4.
It integrates some of the best modern tools and snippets to create advanced static websites.
It's mainly based on Yarn, a reliable and easy to use package manager, webpack, a module bundler capable of packaging almost any kind of asset, and Sass, one of the most powerful CSS extension language.
All this combined with the simplicity of Ruby and its gems, some reinvented powerful snippets, and the best available linters and debuggers.
You must have the following tools installed to use this boilerplate:
Start a new project in your current directory
$ middleman init -T gabrielecanepa/middleman-webpackor in a new one:
$ middleman init <project-name> -T gabrielecanepa/middleman-webpackYou can also set up an alias like middleman:webpack in one of your shell profiles
# ~/.bash_profile
alias middleman:webpack="middleman init $1 gabrielecanepa/middleman-webpack"and use it to quickly initialize a new project.
💡 A good usage example, that will be used through this wiki, is the same documentation website of the template
$ middleman server # Run a local server
$ middleman build # Build the static files
$ middleman deploy # Deploy the built siteYou'll find the main settings of your website in data/site.yml.
The properties you set up here will be used by the auto_display_meta_tag helper to inject specific tags in your views.
The default configuration
produces the following tags for the homepage:
Any tag can be overwritten (or created) in each page or layout with the set_meta_tag helper (see source/index.html.erb)
<% set_meta_tags title: data.site.name + ": " + data.site.description,
full_title: false %>or frontmatter (see source/404.html.erb):
---
title: Page not found
description: This page was not found by Middleman webpack 🤔
keywords: page, not, found
---💡 The full title option is set to true by default, and uses
-as separator. You can set this option to false to use an indipendant title, or change the symbol you want to use as separator (e.g.<% set_meta_tags title: "Secondary page", separator: '∙' %>)
The icon you specify in the favicon field (_favicon.svg by default) must be relative to source/assets/images.
The leading underscore prevents it from being copied into the build directory. The image format should be either PNG or SVG.
In production, it will be used to generate your favicons and show the correspondent tags in your layouts, thanks to the auto_display_favicon_tags helper.
You can change the favicons you want to produce in your config.rb, and the tags generated by the helper will change dynamically.
The favicons set by default
# config.rb
set :favicons, [
{
rel: 'apple-touch-icon',
size: '180x180',
icon: 'apple-touch-icon.png'
},
{
rel: 'icon',
type: 'image/png',
size: '32x32',
icon: 'favicon32x32.png'
},
{
rel: 'icon',
type: 'image/png',
size: '16x16',
icon: 'favicon16x16.png'
},
{
rel: 'shortcut icon',
size: '64x64,32x32,24x24,16x16',
icon: 'favicon.ico'
}
]generate the following tags and relative icons:
<link rel="apple-touch-icon" sizes="180x180" href="apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="favicon32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="favicon16x16.png">
<link rel="shortcut icon" sizes="64x64,32x32,24x24,16x16" href="favicon.ico">This repo has been updated to use Tailwind CSS 1.x. It's fairly opinionated, but a great way to style apps.
Your website setting must be imported first and contain the variables, mixins and rules you will use in your style. Check the Sass documentation for a better usage of this tools.
Import external stylesheets right after your website settings, and before any eventual setting overriding the default library configuration.
Any stylesheet added with Yarn can be imported into your stylesheet files with an @import statement followed by the path relative to the node_modules folder.
💡 You can also import stylesheets in your JavaScript files. Check the Yarn and webpack section
The repository comes configured with Yarn, webpack and the following loaders:
- Babel for JavaScript
- style-loader, css-loader, and sass-loader for CSS and SCSS
webpack has been integrated thanks to the in-built external pipeline extension (find the configuration in config.rb), that allows Middleman to run multiple subprocesses.
Every time a server is run (in development or production), also the relative Yarn command gets executed (yarn run start or yarn run build), which runs, in turn, the right webpack process.
💡 Want to set up your application with a different JavaScript pipeline? Have a look at the relative Middleman documentation
You can install a new package with the following command:
yarn add <package-name> [--dev]In your JavaScript files, import modules from a package with the import command:
import tippy from 'tippy.js';
tippy.setDefaults({
arrow: true,
arrowType: 'round',
duration: [275, 200],
inertia: true
});You can also import CSS and SCSS in your scripts by following the path relative to the node_modules folder.
For example, to import the same Bootstrap grid style:
import 'bootstrap/scss/bootstrap-grid.scss';💡 If you want to extract CSS/SCSS into separate files check the mini-css-extractor-plugin
webpack it is capable of transforming, bundling, or packaging just about any resource or asset, but can be tricky to configure.
If you want to understand and master a wide variety of tools and features that this tool offers, have a look at the official webpack guides.
You can embed inline SVG icons in your views thanks to the svg_tag helper:
svg_tag(file_name, attributes = {})The file_name has to be relative to your images folder. HTML attributes (id, class, title, etc.) can be specified directly with the helper.
The biggest advantage of using inline SVGs is being able to have complete control over the different shapes using CSS and JavaScript (check the footer of the documentation website 😎).
You can find an example in your source/index.html.erb:
<%= svg_tag "logo.svg", class: "middleman-logo" %>Finally, when you are ready to deliver static code, you will need to build the site. Using the command-line, from the project folder, run the corresponding Middleman command:
$ middleman buildThis will create a static file for each file located in your source folder, compile your webpack bundles, and generate the specified favicons.
Any enabled build-time features (such as minification and compression) will be executed. You can find the extensions already activated in the build-specific section of your config.rb.
After building the site you will have everything you need within the build directory.
A very handy tool to deploy a build is middleman-deploy. By default, it has been configured to deploy your website on GitHub Pages via the gh-pages branch, and build the static files before any new deployment.
To activate the extension, simply run from your command-line:
$ middleman deployYou can test your code thanks to the Rake gem, that allows to write tests and tasks in standard Ruby syntax.
By default, 3 tasks have been defined, each one testing the style for a specific language (JavaScript, SCSS and Ruby). Run them with the rake command:
If you use Atom as text editor, you can install linter-eslint, linter-rubocop and linter-stylelint to check your style while you type. If you use Sublime Text, have a look at the ESLint, RuboCop and stylelint packages.
A simple 404 page has already been provided. Use it to display a custom page when visitors attempt to access paths that you haven't defined:
- Fork the repository
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -m "Add some feature") - Push to the branch (
git push origin my-new-feature) - Create a new pull request