Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    portentpublic

    portent: perfect websites

    Build Status Dependency Status Codacy Badge Code Climate bitHound Score

    Simple best-practices static website generator.

    Quick start

    Run npm install --save portent, then add two scripts to your package.json:

    "scripts"{
        "start": "portent run .",
        "build": "portent build .",
        "deploy": "portent deploy . my-ssh-server:path/to/destination"
    }

    Then create a pages directory, maybe a few more files as described below, run npm start and start editing and using your website.

    File hierarchy convention

    The website project directory should look as follows:

    /css
      header.css
      typography.less
        whatever.ie9.css
    /errors
      404.html
    /img
      favicon.png
      p1.jpg
      logo.png
    /js
      /_stuff
      fluidImages.js
      base.js
    /pages
      index.html
      about.html
      _fragment.html
    /static
      other-public-files.txt
    htaccess
    robots.txt
    

    Anywhere in the tree files and directories prefixed with an _ are ignored.

    The structure above will produce a website that responds to URLs / and /about.

    Page structure

    pages directory contains actual routes for pages in the website. Every html file inside is a single URL route. Pages with Unicode names do not work perfectly, but if they work for you, great.

    It is recommended to include a tag in every template and refer to files and URLs relative to the root of the project, without using a leading slash. For example, to link from projects/foo to about, use a string about, not ../about. A workflow different from this has undefined behavior.

    If pages contains a file transform.js, it will be used to modify HTML programatically:

    module.exports = function(path, $){
      $.root().append('Hello, world');
    }

    Errors

    errors directory contains templates for HTTP errors.

    CSS

    All CSS are combined and included in your HTML.

    To refer to images, use url('foo.png') syntax, where the images are located in the same directory as your CSS file, or deeper with url('foo/bar.png').

    If a file ends in .less, it will be processed with LESS. Take care to ensure your submodules are hidden behind an _ name, or else they will be included twice.

    If a file ends in .ie9.css or ie9.less (or ie 8), the files will be conditionally connected only in Internet Explorer.

    Portent-base

    Portent includes a base stylesheet that promotes some best practices. Import it using @import 'portent/base.less'.

    JS

    All JavaScript files are combined and included in your HTML.

    If a file ends in .min.js, it will not be processed, but included as is in a separate bundle and will run before your regular scripts.

    If a file ends in .cjs.js, it will be Browserified. Take care to ensure your submodules are hidden behind an _ name, or else they will be included twice.

    HTML

    HTML files are processed using nunjucks templating syntax (version 2) that is primarily useful for its extends tag.

    Portent-base

    Portent includes a base template for HTML websites that promotes best practices in HTML authoring. Use it by extending in your templates with {% extends "portent/base.html" %}, and then defining blocks and variables as follows:

    {% extends "portent/base.html" %}
    
    {% block title %}
        Document title
    {% endblock %}
    
    {% block head %}
        <meta name=description content="">
        <link rel=stylesheet href="http://fonts.googleapis.com/...">
    {% endblock %}
    
    {% block body %}
        <header>Website-generic content</header>
        <div>
            Include new custom blocks for further extending:
            {% block content %}{% endblock %}
        </div>
    {% endblock %}
    

    If your website is non-English, make sure to set the language with a {% set lang='XX' %} anywhere in the template.

    Set a theme color for your website to use whenever it is possible to customize browser chrome with {% set themeColor='blue' %}. Any CSS color or syntax works.

    Images

    Images in img will become part of your website.

    If a file favicon.png is present in the root of your images directory, it will be added to your website as a proper favicon, resized and included in HTML. It is recommended to have the base favicon in at least the 196x196 size.

    Static

    Everything in static will become part of your website. Use this to host fonts, videos, other resources of the sort.

    Usage

    Development server

    To develop your website, run a development server in the terminal: portent run . or in Node: portent(directory).server.listen(port).

    Building for production

    To build the website for production, use portent build ., or in Node portent(directory).build(destination, { onWarning: console.log.bind(console) }).

    Deploying

    To deploy the website, portent exposes a nicer way to use rsync on your machine. Run portent deploy . ssh-server:path/on/remote/.

    Keywords

    none

    install

    npm i portent

    Downloadsweekly downloads

    18

    version

    3.2.0

    license

    ISC

    repository

    githubgithub

    last publish

    collaborators

    • avatar