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.
- 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.
- Webpack as a resource bundler (and
- 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 invokeSplide
s 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 sectionBuilding 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
- Pug subtemplates (that can be
include
d)- Fonts served by public Google Fonts CDN
- Scripts to include common design feats
- Node.JS 12 or higher
To create a new project:
- Clone the repo, or produce a new repo from the GitHub template.
- Rename
index.example.pug
toindex.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
directorynpm run dev
will initiate thewebpack-dev-server
on port 80npm 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.
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.
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 thefamilies
array. - Declare these font families in the
tailwind.config.js
file, in thetheme.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.
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 thewebpack.config.js
file. - Rewrite the
/src/scripts/contact.ts
file, or remove it along with any references to it.
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.
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.