Node Package Master

    20ful

    0.3.5 • Public • Published

    20ful

    Static site generator that makes sense.

    Installation

    $ npm init -y
    $ npm install 20ful
    

    Quick start

    $ mkdir -p src/html
    $ cat > src/html/hello.md
    ---
    index: true
    ---
    # Hello world!
    ^D
    $ 20ful
    

    You can also check the example project.

    What it does

    The generator takes in your input files, possibly applies conversions, and writes them out, optionally starting a static web server for development.

    Running and command line options

    20ful build compiles your input files and exits

    20ful watch compiles your input files and watches for changes

    20ful serve all the above, and starts static server, reloading it on change with browser-sync. This is the default.

    20ful proxy <port> starts HTTP proxy server instead and connects to given port. This is useful if your site is not so static and you already have a server running, but would like to watch for changes of the front end files.

    --port

    Port to listen on in serve or proxy mode. The default is 3000.

    Directory structure

    Put all your stuff in src/. It will get compiled and placed into _site/, preserving directory structure. Dot files are ignored.

    Folder src/html/ is special, the "html" part will be stripped in the resulting path, and for files compiled to HTML file name is made a folder, and the content is placed in index.html in it.

    source destination
    src/server-config _site/server-config
    src/assets/css/main.styl _site/assets/css/main.css
    src/html/.git/ ignored
    src/html/mypage.md _site/mypage/index.html

    This also means that if you create two files whose pathnames are different only in html/ part, only one of them will make it to the output location, so don't do that.

    Conversions

    The generator natively supports the following conversions:

    • for HTML: Markdown (.md), Pug (.pug), Nunjucks (.njk)
    • for CSS: Stylus (.styl), Sass (.scss, .sass)
    • for JavaScript: LiveScript (.ls)

    File type is determined by its suffix. All other files are copied as is to their destinations, including plain HTML, CSS, JavaScript, binary files, etc.

    Any file can have YAML-formatted, "---" delimited front matter (FM), which is stripped after processing. Some behavior is defined by the front matter data.

    Front matter attributes

    template: string

    The file is a named template, normally pug or njk. There is no designated location to store your templates, as long as they are within src, nor there are any particular filenames that you must give them. The following template variables are special:

    body

    The rendered file that used this template.

    toc

    Table of content, or navigation, within an <ol>. Built from toc attributes, see below.

    eleventyNavigation

    Synonym for toc.

    css

    Set of <link> attributes referring to CSS files, if cache busting is enabled. See below.

    js

    Set of <script> attributes referring to JS files, if cache busting is enabled.

    All special variables contain HTML and therefore must be passed in unsafe mode. Default template system is always present, and just renders the body, so you may want to name your first template "system" to override it.

    layout: string

    The file is rendered using the named template. Possible values:

    • some name named template is used.
    • none no template is used
    • (attribute not present) template "system" is used

    index: boolean

    If set to true, this file is written to top-level index.html in the output direcory.

    toc: object

    Object, describing a table of content entry. Its attributes:

    • key: (visible label in the TOC link)
    • order: (entries are sorted using this value)

    Table of content is hierarchical and follows the directory structure. To have a useful table of content organize your files:

      My-Stories.md           [FM]  toc:
                                       key: My cool stories
      My-Stories/
         Cool-story-1.md      [FM]  toc:
                                       key: First cool story
                                       order: 10
         Another-story.md     [FM]  toc: ...
    

    There is no need (and no way) to specify a parent, you can rearrange your pages just moving them around, and TOC will be automatically rebuilt, and will render to an ordered list: <ol><li><a href='/'>My cool stories</a...

    bust-cache: boolean

    If set to true, enables cache busting for this CSS or JS file. Cache busting is done by automatically adding a hash suffix to the filename, changing as the file content changes. Template variables css and js will have the whole sequences of <link> and <script> attributes which you need to pass verbatim to templates.

    For all files that compile to CSS css variable stores a sequence of link tags:

    <link rel=stylesheet href='/path/filename-34856.css'><link ...
    

    For all files that compile to JavasScript js variable stores a sequence of script tags:

    <script src='/path/filename-51536.js'><js ...
    

    In a pug template, put | !{css} and | !{js} within the head.

    order: number

    This controls the order of tags within cache-busted css and js variables.

    options: object

    Options to pass to the compiler. See the jstransformer for the relevant language. Examples:

    main.ls:

    ---
    options:
       bare: true
    ---
    f = a >> b
    # LiveScript won't generate top-lever wrapper.
    

    page.pug:

    ---
    options:
        doctype: html
    ---
    p(x-attr)
    // This shall render to `<p x-attr="x-attr">`.
    

    ignore: boolean

    If set to true, this file is skipped.

    Config file

    User configuration is read from ./20ful-config.yaml. The defaults are:

    source:  src
    outroot: _site
    markdown-it-plugins:
      markdown-it-mark: true
      markdown-it-multimd-table:
        headerless:   true
        multiline:    true
        rowspan:      true
    

    Markdown-it-plugins are what they appear to be. To add a markdown-it plugin:

    • install markdown-it-plugin-<name>
    • mention it in the config (false to disable)

    If the plugin takes options, give them as sub-keys.

    Motivation

    I was amazed by the amount of effort put by people into something as simple as site generators, and at the same time frustrated by the absence of obvious functionality, such as preprocessing of CSS.

    This project is not nearly as grandiose (under 350 lines of code as of now), still it covers most basic needs.

    Install

    npm i 20ful

    DownloadsWeekly Downloads

    51

    Version

    0.3.5

    License

    MIT

    Unpacked Size

    42.8 kB

    Total Files

    17

    Last publish

    Collaborators

    • punund