Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/epochblue/nanogen

A very small static site generator written in Python.
https://github.com/epochblue/nanogen

blog-engine cli command-line python static-site-generator

Last synced: 5 months ago
JSON representation

A very small static site generator written in Python.

Awesome Lists containing this project

README 

          
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-``

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

`_.



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