{% load demotags %} PyBlue Home {% assets %} {% markdown %} # Welcome to PyBlue {% img css="right thumb" pattern="fractal1" %} A simple static site generator. PyBlue allows the reuse of visuals (header/footer) and data across many pages and it can generate static sites from dynamic templates. This page was created with PyBlue from the file located in [docs/index.html][index] [index]: https://github.com/ialbert/pyblue-central/tree/master/docs/index.html ### Why PyBlue? There is no shortage of static html generators. PyBlue is a personal project that aims to address my personal annoyances with other options. I have evaluated quite a few alternatives even used some over longer periods of time. None of the choices did what I needed for my work. Hence came the motivation to write my own. {% img css="right thumb" pattern="fractal3" %} The following are some of the reasons why PyBlue exists: 1. All features are optional! 1. Requires no special configuration to get started. 1. Automatic linking! Reorganize the site without having to worry about broken links. 1. Automatic syntax highlighting of code. 1. Integrates seamlessly with Markdown. And then of course it has many advanced features: 1. Advanced templating [Django Templating][django] system and all that it offers. 1. Support extending the template language via custom template tags. 1. Pyblue can be told to load data into any page. 1. The template system can operate on data loaded into the page. 1. Tiny codebase, eminently hackable. PyBlue is around 500 lines of code. 1. Runs on all Python version from 2.7 to 3.6 ### Install pip install pyblue --upgrade Or download it from the [PyBlue at PyPI](https://pypi.python.org/pypi/pyblue/). Alternatively to install the latest version: git clone git@github.com:ialbert/pyblue.git cd pyblue python setup.py develop ### Usage The documentation that you read now has been created from the files in the [docs][docs] folder. * Launch pyblue to serve a directory `pyblue -r docs` * View your site by visiting `http:://localhost:8080`. * Edit your pages and make changes. Reload the page to see your edits live. * Finally, generate the static output with: `pyblue -r docs -o html` To see extra help on options run: `pyblue -h` [docs]: https://github.com/ialbert/pyblue-central/tree/master/docs/ ## Features ### Context {% img css="right thumb" pattern="fractal2" %} The pages are rendered through the [Django Template][django_templates] language. To make use of the templating you need to understand how this templating language works. By default there is extra data associated with each page. For example the {% verbatim %}{{ page }}{% endverbatim %} variable is available: * Writing: {% verbatim %}{{ page.name }}{% endverbatim %} will produce: {{ page.name }} * Writing: {% verbatim %} {{ page.last_modified }} {% endverbatim %} will produce: {{ page.last_modified }} * Writing: {% verbatim %} {{ page.size|filesizeformat }} {% endverbatim %} will produce: {{ page.size|filesizeformat }} Note how in this last case we also made use of the filesizeformat builtin filter of Django. Users may add more information even load a python module into the page. More details on the {% link "context.html" %} page. ### Links and Images Users can also make use of pyblue specific template tags that are automatically available. For example the `link` tag generates relative paths to any other file. * {% verbatim %}{% link "context.html" %}{% endverbatim %} will produce the following: {% link "context.html" %}. * {% verbatim %}{% link "context.html" text="Click me now!" %}{% endverbatim %} will produce the following: {% link "context.html" text="Click me now!" %}. {% img css="right thumb" pattern="fractal4" %} Important: Note how in this case the file is located in info/context.html Yet we did not have to put the full path the linking tag. `PyBlue` found the file and linked it properly. Why did that work? The {% verbatim %}{% link "context.html" %}{% endverbatim %} command performs a regular expression search on all files in the directory and once it finds a match it produces a link to it with the proper relative path. This keeps links correct even if the files were to be moved later. Note that the search string is a regular expression and it is sufficient to specify the shortest unambiguous part of the filename. `PyBlue` will find it and link it. > As a matter of fact this is one reason PyBlue was written. I got very tired of fixing > broken links after a site reorganization. PlyBlue now does it automatically. The {% verbatim %}{% img "fractal.png" %}{% endverbatim %} tag works similarly to the link tag. but generates image links. It also takes the `css` parameter where css classes may be passed to the image. The CSS itself will have to be defined in the page header or the site asssets. ### Markdown To include markdown content into an HTML document place it between {% verbatim %}`{% markdown %}` and `{% endmarkdown %}`{% endverbatim %} template tags. ### Fenced code blocks When using markdown fenced codeblocks may be used. Include code between ``` symbols that can also take language hints: ```python import sys for line in open("data.txt"): print line.strip()[:10] ``` ### Include code To include syntax highlighted code from a file write {% verbatim %}{% code "context.py" lang="python" %}{% endverbatim %} {% code "context.py" lang="python" %} This file is also special because of its name: `context.py`. The contents of this python module is available inside every page under the name of `context`. For example writing {% verbatim %}`{{ context.greeting }}`{% endverbatim %} produces: {{ context.greeting }}. This is where the full power of `pyblue` shows. You see, you can go wild and add any and all data that you might need. Call out to any program, read any file etc. It is `Python` all [the way down][turtles]. [turtles]: https://en.wikipedia.org/wiki/Turtles_all_the_way_down ### Include markdown Alternatively one can instruct PyBlue to include the rendered content of markdown files. To include the file `example.md` in its original content one would use {% verbatim %}{% code "example.md" %}{% endverbatim %} this would produce: {% code "example.md" %} This same file could be included as html with {% verbatim %}{% markdown_file "example.md" %}{% endverbatim %} In that case it will produce the following: {% markdown_file "example.md" %} Note how in both cases an automatic search takes place PyBlue will find the location of the file `example.md` wherever it might be on the root directory. That's super convenient. ### Advanced templates The [django templating][django_templates] system allows extending or including other templates or sections. * {% verbatim %}{% extend "sometemplate.html" %}{% endverbatim %} * {% verbatim %}{% include "sometemplate.html" %}{% endverbatim %} These features support template inheritance and composition. Read on from more {% link "advanced.html" %} and {% link 'mdtest.html' %} ### Licensing * PyBlue uses the [MIT license][license]. * PyBlue is being developed by Istvan Albert see https://github.com/ialbert * PyBlue has been inspired by [PyGreen][pygreen] created by Nicolas Vanhoren see (https://github.com/nicolas-van/pygreen) but over the years it has diverged so much that it probably does not use any code from that codebase. [django]: https://www.djangoproject.com/ [markdown]: http://en.wikipedia.org/wiki/Markdown [pygreen]: https://github.com/nicolas-van/pygreen [license]: https://github.com/ialbert/pyblue/blob/master/LICENSE.txt [bootstrap]: http://getbootstrap.com/ [django_templates]: https://docs.djangoproject.com/en/1.9/ref/templates/language/ {% endmarkdown %}