search

pixelastic / norska

🏔️ Custom SSG using Pug, Webpack, PostCSS and Tailwind.
https://projects.pixelastic.com/norska/
MIT License
8 stars 0 forks source link

Add a theming system #70

Closed pixelastic closed 4 years ago

pixelastic commented 4 years ago

Norska should support a theming system so I can use it on various site while sharing the same layout / features. Use case is quickly deploying documentation websites for my projects, while still being able to fix rendering issues / add features to all of them only by updating one package.

Themes can be comprised of several parts: the wrapping layout, the custom CSS and Tailwind config, the new _data/ files, etc. For this first version, we'll only focus on the layout itself.

Currently, norska init copies a default layout to src/_includes/layout/core.pug, and each .pug file starts with an extend targeting this file. .md files have the layout: key in their frontmatter.

With a theme system, the layout will no longer be fetched from the project src/_includes/layouts folder by default, but from the theme module itself. Layouts with the same name in the project tree will take precedence of course, so each project can create its own layout if needed.

Norska will not ship default layouts, but with a default theme, and the norska codebase will be updated to fetch layouts from the theme if possible. That way, we eat our own dog food by making sure even the default theme correctly works with the theme code.

Defining the layout

Today, .md files can define the layout from their frontmatter, but .pug files have to extends it. To simplify the process and have something similar in both cases, .pug files will now allow a frontmatter-like header:

//- ---
//- layout: custom
//- title: My title
//- ---

Wrapped in comments, but using a frontmatter-like syntax, this will be parsed by norska and works just like it does with markdown.

Norska will read and parse those comments and extract the layout name. If none is passed, it will default to default. It will then look for layouts with this name in the src/ folder first. If none is found, it will check if a theme with such a name is available and load the layout from the theme.

Norska will then prepend the extend line at the start of the pug file, pointing to the layout it found.

norska.config.js can be used to define a site-wide layout

pixelastic commented 4 years ago

Partial theme support has been added in v1.0

It supports layouts, includes and CSS overrides from the theme