Metadata-Version: 1.1
Name: nanogen
Version: 0.7.2
Summary: A very small static site generator
Home-page: https://github.com/epochblue/nanogen
Author: Bill Israel
Author-email: bill.israel@gmail.com
License: MIT
Description: nanogen
        =======
        
        A very small static site generator written in Python.
        
        .. image:: https://img.shields.io/pypi/v/nanogen.svg
            :target: https://pypi.python.org/pypi/nanogen
            :alt: Latest PyPI version
        
        
        Installation
        ############
        
        The best way to install ``nanogen`` is through ``pip``::
        
            $> pip install nanogen
        
        
        If you don't want to install it via ``pip``, you can install it by
        hand::
        
            $> git clone https://github.com/epochblue/nanogen
            $> cd nanogen
            $> python setup.py install
        
        
        Note : To avoid possible dependency version issues, I advise
        installing ``nanogen`` into a virtual environment, rather than
        installing it globally.
        
        
        
        How To Use
        ##########
        
        Initializing
        ~~~~~~~~~~~~
        
        Once ``nanogen`` is installed, navigate to the directory you'd like to
        use as your new blog. Our examples will use a ``blog`` directory in our
        home directory::
        
            $> mkdir blog
            $> cd blog
        
        Once there, run ``nanogen``'s ``init`` command to get started::
        
            $> nanogen init
        
        Running this command will generate the basic directories used by
        ``nanogen`` to build your static site. When this command completes, your
        ``blog`` directory will look like this::
        
            ~/blog
            |-- _posts
            `-- _layouts
        
        These are all the only two folders required by ``nanogen``, and cannot
        currently be changed by the user. If you're creating a blog-style
        site, your individual posts will go in the ``_posts`` directory, and
        your site's templates will go in the ``_layouts`` directory.
        
        
        
        Publishing Posts
        ~~~~~~~~~~~~~~~~
        
        For ``nanogen`` to "publish" your posts, two things must be true:
        
        #. they must be located in the ``_posts`` directory, and
        #. they must be named like this: ``<year>-<month>-<day>-<name>.<ext>``
        
            - ``<year>`` is a 4-digit year; ``<day>`` and ``<month>`` are
              two-digits
            - the ``<ext>`` must be a valid `Markdown`_ extension: ``md``,
              ``mdown``, ``markdown``
        
        Files in this folder that don't match the above pattern will be
        skipped and will not be part of the generated site. The content of the
        post files follows the somewhat-standard format of `YAML`_ front- matter
        followed by a `Markdown`_ body.  Below is an example of what this format
        looks like::
        
            ----
            title: This is an example blog post
            slug: example-post
            layout: post.html
            ----
            
            Everything from this point forward will be process as **Markdown**.
            You can _format_ your text however you please. Please check out the
            Markdown Documentation if you're unfamiliar with Markdown syntax.
        
        
        The only required field in the front-matter is ``title``. Two optional
        fields are ``slug`` and ``layout``. If these aren't present, defaults
        will be used. ``slug`` defaults to the ``<name>`` field in the post's
        filename, and ``layout`` defaults to ``article.html``. Any other fields
        you add to the front-matter will be ignored by ``nanogen``, but are
        passed to and can be used by your templates.
        
        Files in ``_posts`` will be "published" into folders based on the date
        in their filename, which is assumed to be their publish date. For
        example, a blog post with the filename ``2014-11-08-example-post.html``
        will be processed into a date-specific folder:
        ``site/<year>/<month>/<name>.html``.
        
        Draft posts aren't an official feature of ``nanogen``, however they are
        possible. By default, when ``nanogen`` generates a site it ignores any
        directories and files that start with a ``_`` or a ``.``. If you'd like
        to maintain drafts of your posts, you can create a ``_drafts`` folder
        and ``nanogen`` will dutifully ignore it during site generation.
        
        
        Publishing Non-Post Content
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        For pages that aren't intended to be blog posts (An index page, a post
        archive, About pages, Contact pages, etc), ``nanogen`` will simply pick
        them up as it processes files and folders. These files don't use the
        front-matter/Markdown format, but are instead treated as raw
        templates. Their location relative to the root folder will determine
        their placement in the published site folder.
        
        
        Static Files
        ~~~~~~~~~~~~
        
        If you have any files that you'd like to include in the published site
        you can use the ``keep`` field in the site configuration. Common uses
        for this would be CSS or JavaScript files that you need to help render
        the final site. See theConfiguration section for more information.
        
        
        Building
        ~~~~~~~~
        
        Once you're ready to generate your site, you can use the ``build``
        command::
        
            $> nanogen build
        
        This command will walk your directory, process any valid files it
        finds, and will write all the generated files into a ``_site`` folder.
        Although you will want to check this on your local development system,
        the ``_site`` folder can be uploaded to your web host as-is and served
        as the root for your web server.
        
        *Note*: before each build ``nanogen`` will reset the ``_site``
        directory, so it's not a good idea to add anything to the ``_site``
        directory that you intend to keep between builds.
        
        
        
        Cleaning
        ~~~~~~~~
        
        ``nanogen`` provides a ``clean`` command to remove your ``site`` folder
        if it somehow gets corrupted or you would like to generate your site
        from scratch::
        
        
            $> nanogen clean
        
        
        Configuration
        ~~~~~~~~~~~~~
        
        In addition to the per-post configuration (front-matter), there is
        also a site-wide level of configuration available to all posts and
        templates. This configuration is stored in ``config.yaml`` in the
        project root. It isn't strictly required, but ``nanogen`` will warn you
        if it doesn't find one. Below is an example of a typical ``config.yaml``
        file::
        
            title: cubicle17
            author: Bill Israel
            url: http://cubicle17.com/
            keep: [static, css, js]
        
        None of the fields in ``config.yaml`` are required, but anything defined
        will be passed to all templates. In the templates, anything defined in
        this file will be available under a special variable called ``site``.
        For example, to use the ``url`` variable from the above example, use
        ``{{ site.url }}`` in your template.
        
        ``keep`` is the only key in the configuration file that ``nanogen``
        explicitly looks for. If it's found, ``nanogen`` expects it to be a
        `YAML`_ list of directories (relative to the project's root dir) that
        need to be copied into the generated site structure.
        
        
        Templates
        ---------
        
        ``nanogen`` uses `Jinja2`_ for its templating. If you need information
        about how Jinja templates work, please `refer to their
        documentation <http://jinja.pocoo.org/docs/>`_.
        
        ``nanogen`` passes a few things to each template, however. To single-
        post pages it passes the site-wide configuration under a variable
        called ``site``, as well as all the information about the single post
        via a variable called ``post``. To all other templates ``nanogen`` again
        passes the site-wide configuration under the ``site`` variable, as well
        as a list of all posts under a variable called ``posts``.
        
        
        Misc Notes
        ----------
        
        
        #. ``nanogen`` doesn't provide a ``watch`` mechanism found in other
           static site generators. If you'd like this functionality, you can
           use a tool like `Watchman`_ or simply run ``build`` in an infinite
           loop. The following example will run a build every second::
        
            $> while [ 1 ]; do nanogen build; sleep 1; done
        
        
        License
        -------
        
        ``nanogen`` is MIT licensed. Please see included ``LICENSE`` file for
        more information.
        
        
        Author
        ------
        
        `Bill Israel`_ - `bill.israel@gmail.com`_
        
        
        .. _Markdown: http://daringfireball.net/projects/markdown
        .. _YAML: http://yaml.org/
        .. _Jinja2: http://jinja2.pocoo.org/
        .. _Watchman: https://facebook.github.io/watchman/
        .. _Bill Israel: http://billisrael.info/
        .. _bill.israel@gmail.com: mailto:bill.israel@gmail.com
        
        
Keywords: ssg,generator,static site generator,blog
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Utilities
Classifier: Topic :: Software Development :: Libraries :: Python Modules
