benglynn / press Goto Github PK

View Code? Open in Web Editor NEW

0.0 0.0 0.0 540 KB

Joyful static site publishing.

Home Page: https://www.npmjs.com/package/@benglynn/press

License: MIT License

TypeScript 89.84% HTML 9.11% JavaScript 1.05%

webpack static-site-generator typescript functional

press's Introduction

Press

Press integrates tightly with Webpack to take care of your static site's content. Feed it with templates and a tree of markdown files and it emits HTML, templated and transofmed by customisable pipe of composable functions.

Quick set up

Clone and play with the Press demo to see Press in action. Press is fast and works well with Webpack DevServer, live reloading when your content changes.

What does Press need to work?

Press is fed with one or more pug templates, and with a directory structure where each directory contains an index.md file:

markdown/
├── index.md
├── french-press/
│   └── index.md
└── tea-pot/
    └── index.md

As well as its content, each markdown file may have a yaml metadata header, for example:

---
datePublished: 2020-02-17
tags:
 - vessel
---
# French press

A device for brewing coffee.

How does Press work?

Press walks the markdown directory and for each page firstly pipes a Directory through a series of transformations into a Page and secondly reduces a site-wide RenderContext.

The pages and render-context may then pass through a render pipe to create HTML.

Press is built to be customised

The transformations and render-context can be anything you want. Presss is designed to accept any pipeables and reducers with compatible input and output types.

For example, Press uses pug for templating, but you could use a different template engine if you replace the pug sepcific parts.

Much more on customisation TODO...

More transformations in the pipeline

It's early days, more pipeables and reducers are on the way, please see issues for details.

Developing Press

npm run lint
npm run build
npm test

press's People

Contributors

press's Issues

Only minify in production mode

In development mode leave html un-minified, only minify for production.

Double escaping in code blocks

Template cache is not destroyed between renders

Code highlighting

Part of the render pipeline. Use prism to expand code blocks. Also, related CSS.

page hash

Create a page hash, so that any page datum may be found by path
For example pages['/'] retrieves the home page datum
Update tags to use the hash

Template functions

Allow functions (such as formatters or common extractions from metadata) to be passed in to createPressWebpack.

Normalise pipeables

Consider changing the markup-html, pug-render and highlighting pipeables to work on a single page, managing the pages mapping in the pipe.

Clearer composition

Separate the step-up from dir to page and the page pipeline
Diagram in the readme each separate parameter, step-up, page-pipe, reducers, render-pipe
Separate out each of these in the defaults, break the single file into three

Template compile/render errors in the browser

As well as in the console, compile and render errors should be visible in the browser too. Even if this is just in a <pre/> on an unsettled page for now, the user will be instantly aware of the issue. Also consider keeping the bundle on this page, so that fixing the error results in a live reload of the fixed page.

Images (and generic Webpack assets)

Allow markdown to reference images. Use scan to create variants with a site-wide spec.

This is likely to break down into three related tasks:

image dependencies

A page-pipe pipeable. Glean from markdown metadata and content. Changes to any image source then trigger a render.

Image versions

Part of the render pipeline as we don't want to do this work unnecessarily. Generate Buffer for each image variant.
This is destined to be emitted much like html, perhaps a generic assets would mean tapAsyncCallback is better encapsulated?
Related to the previous point, why is Webpack 'hidden' from CompileContext? Perhaps address that here, the webackReducer can always be stubbed in tests

figure

Client code to enhance the low-res variant in source to a responsive image.