Flores

Minimalist static site generator.

Features

• Fast markdown parser with GFM syntax using markdown-it.
• Create a website theme with rich and powerful Nunjucks templating engine.
• Write modern CSS with PostCSS and postcss-preset-env.
• Syntax highlighting using highlight.js.
• Automatically generates table of contents using markdown-it-table-of-contents.
• Automatic sitemap generation using sitemap.js.
• Built-in web server for previewing your generated website using express.
• Development server with file watcher that are able to regenerate the website and reload the browser automatically.

Getting Started

1. Download the Starter Template

Run the following command on your terminal to download Flores starter template.

$ wget https://github.com/risan/flores-starter/archive/master.zip \
    -O master.zip && \
    unzip master.zip && \
    mv flores-starter-master my-blog && \
    rm master.zip

It will automatically download the starter template and unzip it to my-blog directory.

Or you can also download the starter template and unzip it manually.

2. Install All Dependencies

Within your project directory, run the following command to install all dependencies:

$ npm install

3. Generate the Website

Run the following command to generate your website for production:

$ npm run build

For development purpose, you can preview your generated website with the built-in server:

$ npm run serve

Flores also comes with file watcher that can rebuild your website and reload the browser automatically:

$ npm run build

Guide

Directory Structures Overview

By default Flores project has the following directory structures.

|- src/
|  |- assets/
|  |- templates/
|  |  |- collection.njk
|  |  |- post.njk
|  |
|  |- category-1/
|  |  |- foo.md
|  |
|  |- category-2
|  |  |- bar.md
|  |
|  |- baz.md
|
|- public/
|- site.config.js

• /src: This is where your website data resides (markdown files, css files, templates, images, etc).

• /assets: This is where you store your CSS files.

• /templates: This is where you store your template files.

• /category-1 and /category-2: Store your markdown file within a directory to create a hierarchical category. The URL for your post will follow the markdown file location:

  /src/category-1/foo.md => /category-1/foo.html
  /src/category-2/bar.md => /category-2/bar.html
  /src/baz.md => /baz.html

• /public: This is where the generated website will be stored.

• site.config.js: The configuration file.

Available Commands

There are three available commands: build, serve, and watch.

build

Run the build command to generate the website for production. By default the website will be stored in /public directory.

$ npm run build

serve

Run the serve command to preview your generate website. This command will generate the website and start the built-in Express server. By default your website will be served on localhost:4000.

$ npm run serve

watch

Run the watch command to start the development server and the file watcher feature. It can regenerate the website and reload the browser automatically on file changes.

$ npm run watch

API

flores.build

Generate the website.

flores.build([options])

Parameters

• options (Object): The configuration options.

flores.serve

Generate the website and serve it over the built-in Express server.

flores.serve([options])

Parameters

• options (Object): The configuration options.

flores.watch

Generate the website and start the built-in Express server. It will also start the file watcher. On file changes, it will automatically regenerate the website and reload the browser.

flores.watch([options])

Parameters

• options (Object): The configuration options.

Configuration Options

Configuration options is an optional Object that you can pass to build, serve, or watch function.

• env (String): The environment name, default to process.env.NODE_ENV. If the NODE_ENV environment variable is not set, production will be set. Note that for serve and watch methods, the env value will always be set to development. When it's set to production, the generated HTML and CSS files will be minified.

• url (String): The website URL, default to http://localhost:4000. Set the correct pathname if you don't serve the website on the root directory—like Github pages for repository (e.g. http://example.com/blog). For serve and watch, the hostname will always be set localhost and pathname will always be empty.

• basePath (String): The base path of your website project directory, default to the current working directory process.cwd().

• sourceDir (String): The directory for the website source relative to the basePath, default to src.

• outputDir (String): The directory where the generated website will be stored relative to the basePath, default to public,

• templatesDir (String): The templates directory relative to the sourceDir, default to templates.

• assetsDir (String): The CSS assets directory relative to the sourceDir, default to assets.

• defaultDateFormat (String): The default date format to use, when using dateFormat filter, default to YYYY-MM-DD HH:mm:ss. Check date-fns format() documentation for all accepted format.

• defaultTemplate (String): The default template name for the markdown post, default to post.njk. You can override the template for individual post by providing the template field on the post's front matter.

• defaultCollectionTemplate (String): The default template name for the markdown post collection page, default to collection.njk. You can override the template for individual post collection page by providing the template field on the page's front matter.

• copyFiles (Array): List of files or file patterns to copy, default to:

  ["images/**", "robot.txt", "**/*.html"]`

• markdownAnchor (Object): The markdown-it-anchor plugin options, default to:

  {
    permalink: true
  }

• markdownToc (Object): The markdown-it-table-of-contents plugin options, default to:

  {
    containerHeaderHtml: "<h2>Table of Contents</h2>",
    includeLevel: [2, 3, 4]
  }

• postcssPresetEnv (Object): PostCSS Preset Env options, default to:

  {
    stage: 3,
    preserve: false
  }

Related

• flores-cli: The CLI tool for this module.
• flores-starter: Flores starter template for blog.

License

MIT © Risan Bagja Pradana