{% load demotags %}
{% site_assets %}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 static output with: pyblue -r docs -o html
To see extra help on options run: `pyblue -h`
- - -
### Features
- - -
#### Context
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.
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
Users can also make use of pyblue specific template tags that are
automatically available. For exmple `link` is such a tag that generates
the proper relative path to any other template or file.
* {% verbatim %}{% link "context.html" %}
{% endverbatim %} will
produce the following: {% link "context.html" %}.
* {% verbatim %}{% link "context.html" text="Click the context now!" %}
{% endverbatim %} will
produce the following: {% link "context.html" text="Click the context now!" %}.
Important: Note how in this case the file is located in info/context.html
Yet we did not have
to put that into the linking tag. `PyBlue` found the file and linked it properly
How does 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 that does not need a full path to the file.
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 broken links
after a more logical reorganization of my sites. That is not a problem now.
- - -
#### Markdown
To include markdown content 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 all `Python` in there.
- - -
#### Include markdown
Alternatively one can instruct PyBlue to include the rendered content of markdown files.
To include `example.md` in original form one would use
{% verbatim %}{% code "example.md" %}{% endverbatim %}
this would produce:
{% code "example.md" %}
This same file could be included as html with {% verbatim %}{% include_markdown "example.md" %}{% endverbatim %}
In that case it will produce the following:
{% include_markdown "example.md" %}
- - -
#### 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.
- - -
#### Overriding templates
By default all templates will be loaded from the root directory of your application
and if not found it will fall back to the `PyBlue` defaults.
Hence to override any
template just add that file with the same name. To override the `site_assets.html` that
contains the custom `css` and `js` modules create your own `site_assets.html` file in your project.
To help demonstrate how this works there is a simple example template tag called {% verbatim %}{% say_hello %}
{% endverbatim %}
Normally this tag will create the output: Hello World! because it is using a template that contains:
Hello World!
This template tag accesses the template file called `say_hello.html`.
If it does not find it in the current directory it falls back to the default location that is part of `PyBlue`.
In the `templates` folder of your root directory create the file `say_hello.html` that contains
{% code 'say_hello.html' %}
Now running {% verbatim %}{% say_hello %}
{% endverbatim %} will produce: {% say_hello %}
- - -
#### Custom template tags
`PyBlue` comes with a few simple template tags such as `link` and `img` but it
also allows you to extend your templates with so called [custom template tags][templatetags].
There are some requirements nainly on naming.
For that to work your root directory must be an `import` ready python module.
This means a name that only has ascii characters and underscores and the root
directory must contain a file name `__ini__.py`. This file may be empty.
Once this is set up you may add your templatetags directory into the root folder as
desribed in the [custom template tags][templatetags] documentation.
[templatetags]: https://docs.djangoproject.com/en/1.9/howto/custom-template-tags/
The `docs` root folder has its own `demotags` custom template tag
* {% verbatim %}{% boom 'PyBlue' %}
{% endverbatim %} will produce: {% boom 'PyBlue' %}
- - -
#### Site assets
Add {% verbatim %}{% site_assets %}
{% endverbatim %} to the head tag of the page to
generate the CSS classes needed to syntax color embedded code.
Override the template called `site_assets.html` to modify the assets.
- - -
#### 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 it does
not use any code from it.
[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 %}