Metadata-Version: 1.1
Name: nanogen
Version: 2.1.2
Summary: A very small static blog generator
Home-page: https://github.com/epochblue/nanogen
Author: Bill Israel
Author-email: bill.israel@gmail.com
License: MIT
Description-Content-Type: UNKNOWN
Description: nanogen
        #######
        
        A very small static blog generator written in Python.
        
        .. image:: https://img.shields.io/pypi/v/nanogen.svg
            :target: https://pypi.python.org/pypi/nanogen
            :alt: Latest PyPI version
        
        .. image:: https://travis-ci.org/epochblue/nanogen.svg?branch=master
            :target: https://travis-ci.org/epochblue/nanogen
            :alt: nanogen build status
        
        Purpose
        =======
        
        ``nanogen`` exists solely so I can have a blogging platform I call my own.
        The platform is very intentionally bare bones and simple. The code is
        intentionally utilitarian and realistically less-than-perfect.
        
        If you have an idea for a way to improve this without significantly increasing
        ``nanogen``'s complexity, please open an issue and let me know.
        
        If you're looking for a more fully-featured static site generator, may I
        recommend something like `Jekyll`_ or `Pelican`_ ?
        
        
        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
        manually::
        
            $> git clone https://github.com/epochblue/nanogen
            $> cd nanogen
            $> python setup.py install
        
        
        Note : To avoid possible dependency version issues, I recommend installing
        ``nanogen`` into a virtual environment, rather than 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 ``$HOME``::
        
            $> 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``. When this command completes, the ``blog`` directory will
        look like this::
        
            ~/blog
            |-- _layout
            |   `-- blog.cfg
            `-- _posts
        
        ``_posts`` and ``_layout`` are the only two folders required by ``nanogen``, and
        their names cannot be changed by the user. Your individual posts will go in the
        ``_posts`` directory, and the templates will go in the ``_layouts`` directory.
        
        The ``blog.cfg`` file will hold metadata about your blog (author's name and
        email, along with the site's title, description, and URL). A skeleton version of
        this file is created for your during ``init``. The keys and values contained in
        this file will be passed to your templates under the ``site`` variable. For
        example: your site's title will be be available in the ``site.title`` attribute.
        
        At this time, ``nanogen`` does not come with a built-in theme, so it's up to
        you to create your own.
        
        
        Creating Posts
        --------------
        
        One way to create new posts is by creating a new file in the ``_posts``
        directory. The filename is important and must match the following rules:
        
        1.  The file can't start with an underscore (they are ignored)
        2.  The file's name must match the pattern ``yyyy-mm-dd-<post_title_slug>``
        3.  The file's extension must be a valid Markdown extension (``md``, ``mdown``, or ``markdown``).
        
        To illustrate::
        
            # valid filename
            2015-11-01-this-charming-man.md
        
            # invalid filename
            15-11-1-bigmouth-strikes-again.txt
        
        If you don't want to try to remember all that, you can use ``nanogen``'s ``new``
        command to do it for you. The only required argument to this command is the title of the
        post being generated::
        
            $> nanogen new "Example Post Title"
        
        Running this will create a properly-named and formatted file in the ``_posts``
        directory.
        
        Draft posts aren't an "official" feature of ``nanogen``, however they are
        possible. By default, when ``nanogen`` generates a site it will only look in the
        ``_posts`` folder for files to process. If you'd like to maintain drafts of your
        posts before you publish them, you can create a ``_drafts`` folder next to the
        ``_posts`` folder and ``nanogen`` will ignore it during site generation.
        Alternatively, you can prepend the filename of a draft post with an underscore,
        and ``nanogen`` will skip over it when searching for files to process.
        
        
        Post Content Format
        ~~~~~~~~~~~~~~~~~~~
        
        ``nanogen`` posts don't use `YAML`_ front-matter, so the first line of your post
        will be used for the title of the post. The content of the posts will be
        processed as `Markdown`_ (the Github-flavored variety, complete with
        syntax-highlighted code blocks). A minimal example of a valid ``nanogen`` post
        is this::
        
            ## This will become the title (with hashes stripped out)
        
            **This** will become the post's _content_.
        
        The title will be stripped out of the post's content, though it will be
        available to your themes via the ``post.title`` attribute.
        
        
        Generating Your Site
        --------------------
        
        Once you're ready to generate your site, you can use the ``build``
        command::
        
            $> nanogen build
        
        This command will walk your ``_posts`` directory, process any valid files it
        finds, and will write all the generated HTML files into a ``_site`` folder.
        Although you will want to preview this on your local development
        system (see the following section for how to do this), the ``_site``
        folder can be uploaded to your web host as-is.
        
        
        Previewing Your Site
        --------------------
        
        To see what your site will look like *before* you upload it to a live
        webserver for the world to see, ``nanogen`` provides a built-in server
        that allows you to preview your generated site::
        
            $> nanogen preview
        
        This command will start a server that listens on ``localhost`` port
        ``8080``. Simply open ``http://localhost:8080`` in a web broswer to
        see how your site looks. If you'd like to use a different hostname or
        port, ``nanogen`` provides an option for each (``-h|--host, and
        -p|--port``, respectively). The following example will start a server
        that listens on ``local.dev`` port ``8000`` (http://local.dev:8000)::
        
            $> nanogen preview --host local.dev --port 8000
        
        
        Cleaning
        --------
        
        If your ``_site`` folder somehow gets corrupted, or you'd simply like
        to generate your site from scratch, you can use the ``clean`` command::
        
            $> nanogen clean
        
        There is no undo or confirmation when running this command.
        
        
        ``nanogen`` Themes
        ==================
        
        *Note*: ``nanogen`` doesn't provide any themes out of the box. If you'd like to
        develop your own theme for ``nanogen``, this section should explain how.
        
        ``nanogen`` uses `Jinja2`_ for its templating. If you need information
        about Jinja's syntax, please `refer to their documentation
        <http://jinja.pocoo.org/docs/>`_.
        
        
        Template Files
        --------------
        
        The templates that make up the theme for your ``nanogen`` blog need to be placed
        in the ``_layout`` directory. ``nanogen`` only expects a few files to exist, and
        those files are:
        
        1. ``index.html``
        2. ``post.html``
        3. ``rss.xml``
        
        ``index.html`` will be used as the sites homepage, ``post.html`` will be used to
        generate each individual post, and ``rss.xml`` will be be used to generate your
        blog's RSS feed.
        
        All of your blog's posts will be passed to ``index.html`` and ``rss.xml`` via a
        `Jinja2`_ context variable named ``posts`` (posts will be in reverse
        chronological order). Individual posts will be passed to ``post.html`` via a
        context variable named ``post``. Each post will have the following relevant
        attributes available to use in the template:
        
        * ``html_content`` - the HTML version of the post
        * ``markdown_content`` - the Markdown version of the post (minus the title)
        * ``title`` - the title of the post (will not be processed as Markdown)
        * ``pub_date`` - a Python datetime object representing the publish date of the post
        * ``permalink`` - the relative URL to the post
        
        Please see the ``_layout`` directory in the included example for a basic theme
        you can use to as a jumping off point for your own theme.
        
        
        Static Files
        ------------
        
        If you have any files that you'd like to include in the published site
        (JavaScript files, CSS files, images, etc), place them into a folder named
        ``static`` inside the ``_layout`` folder. This folder will automatically be
        copied into the ``_site`` folder during the build process. No processing will
        be performed on the files within the ``static`` directory.
        
        
        Sites Using ``nanogen``
        =======================
        
        * `http://blog.cubicle17.com/`__ (code is `available here`__)
        
        
        License
        #######
        
        ``nanogen`` is MIT licensed. Please see included ``LICENSE`` file for
        more information.
        
        
        Author
        ######
        
        `Bill Israel`_ - `bill.israel@gmail.com`_
        
        
        .. _Jekyll: http://jekyllrb.com
        .. _Pelican: http://blog.getpelican.com
        .. _Markdown: http://daringfireball.net/projects/markdown
        .. _YAML: http://yaml.org/
        .. _Jinja2: http://jinja2.pocoo.org/
        .. _Bill Israel: http://billisrael.info/
        .. _bill.israel@gmail.com: mailto:bill.israel@gmail.com
        
        __ http://blog.cubicle17.com/
        __ https://github.com/epochblue/blog
        
Keywords: command line,static 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 :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Utilities
Classifier: Topic :: Software Development :: Libraries :: Python Modules
