PUGTAIL

An opinionated project template for designing, developing, deploying and iterating static websites quickly.

Write markup that is easy to read and convey as HTML/CSS, without needing to learn a whole new framework.

Features

A great developer experience thanks to the following toolchain:
- Webpack as a resource bundler (and webpack-dev-server to spin a dev environment in seconds).
- Pug as a templating engine (and pug-plugin to integrate it into Webpack with little fuss).
- PostCSS along with its Preset Env plugin pack (and a browserslist query in the package.json file) to help optimize & polyfill styles.
- TailwindCSS as the design framework.
- TypeScript as a means to write better client-side JavaScript.
Some hand-picked libraries
- Splide to create accessible carousels (and alike UI elements) with ease and flexibility.
- Animate.css to have a defined set of CSS keyframes (animations) to work with.
- RxJS to add readable, async client-side functionality.
A simple project structure
- Scripts to include common design feats
  - /src/lib/scrolling_animations.ts provides a TS type and an RxJS function to easily include animations triggered when scrolling down to elements targetted by query selectors.
  - /src/lib/splides.ts exports a typed function to invoke Splides in your page with very little code.
  - /src/scripts/contact.ts is a simple script to provide submission of a contact form. It depends on an environment file to provide some variables, read section Building in production mode below.
  - /src/scripts/mobile_nav.ts does minor DOM changes in order to provide a responsive navigation menu with a toggle button, akin to most frameworks and CMS.
  - All of these are included in the packaged index.pug.example file
- Pug mixin functions used as building blocks
  - Header & footer
  - Contact form
  - Google Maps iFrame Embed
  - Metatags
  - Icons from awesome free libraries, served through jsDelivr CDN
    - FontAwesome Free
    - SimpleIcons.org
- Pug subtemplates (that can be included)
  - Fonts served by public Google Fonts CDN

Requirements

Node.JS 12 or higher

Getting started

To create a new project:

Clone the repo, or produce a new repo from the GitHub template.
Rename index.example.pug to index.pug to start working.

You have three available commands from the ground-up:

npm run build will build the production-ready static site on /dist directory
npm run dev will initiate the webpack-dev-server on port 8000
npm run watch will build the site automatically whenever a change is made (but will not embed a webserver)

And you can fine-tune the package.json scripts to your heart's contempt.

For everything else, the documentation of each tool in the chain should suffice. There are links to everything this template depends on, do take a look.

Adding images (and other assets)

To include images in your page, create a /src/images directory and add them there. These will not be versioned; this is by design, to help reduce the size of your repo.

But of course, you can change this setup, e.g. if you want/need to use a different folder, or more than one. You just must pay attention to the:

Filepath patterns in the /.gitignore file.
Path aliases in the webpack.config.js file.

Remember to require() all local assets referenced within your .pug templates, otherwise they won't be loaded (this syntax is established by the pug-plugin).

You may also need to support additional image file extensions, if the ones provided in webpack.config.js don't suffice.

Adding or changing typographic fonts

If you want to choose and utilize other fonts than the default ones, you can follow these two steps:

Indicate which ones you'll load at the /src/includes/googlefonts.pug subtemplate, in the families array.
Declare these font families in the tailwind.config.js file, in the theme.fontFamily object. In the future I might be able to provide a mechanism for a single source of truth regarding typography. But for now, you have to keep both files in mind.

Building in production mode

You must supply an /src/environment.prod.ts file to run a production build, otherwise the process will throw an error. This is due to a dependency from the contact form script.

The contact script uses a POST call to an external, protected API for sending mails (whose implementation is left completely up to you, by the way). And as you'd expect, access to that API is meant to be secured. Which is why environment files are unversioned; to prevent leaking related secrets into the codebase.

But if you don't need to include a contact form, you can either:

Comment or remove the NormalModuleReplacementPlugin bits in the webpack.config.js file.
Rewrite the /src/scripts/contact.ts file, or remove it along with any references to it.

Contributing

Pugtail is an early-stage project template. If you have any suggestions, ideas, or find any bugs while using it, please do not hesitate to create an issue, and hopefully stick around to answer any questions.

PRs are also totally welcome.

License

This software is licensed under MIT. See LICENSE.md.

It uses third-party software that may be filed under MIT or other open-source licenses. Please read and respect each license when you use this template.

bglamadrid / pugtail