Dreamii
Project description
The ultimate site builder! It's not one of the many CMS'es but its a template renderer. It renders dynamic and static content. Finally you can manage a site with the editor that you want! It can be serious article writing or just hacking something together live with VIM on a server. This project allows you to do both. Apply professional versioning / backupping of your site using a CVS. Since this system has a local database, that will be included in the CVS setup too. It's suitable for both small and big sites.
Also, consider Dreamii for beginners / customers. It's actually way easier than WYSIWYG. You advise the editor to the user. You can also write your own editor around it and use Dreamii only as renderer. Sky is the limit.
Writing a site using markdown is very convenient since styles are predefined. If you would use Dreamii for some one else, you can just predefine the styles so the user will keep maintaining the style. This is not the case with WYSIWYG enabled sites.
The concept is that primarely markdown will be used using Dreamii but optionally advanced features can be implemented using HTML and Python.
Features
This project allows you to create a site using all of these technologies:
- Jinja2 (v3.1.5+).
- Markdown.
- Syntax Highlighting within Markdown.
- HTML.
- Dynamic Python that works like PHP. Print statements are site content..
- File serving
It will resolve url's to template files what it will render. By visiting /pony, dreamii will resolve the url and resolve template in this order and will try next one if it exists:
- pony.md
- pony.html
Markdown files have priority since they can use a html page with the same name as template to extend from.
It will resolve root (/) into resolving index.md or index.html. If both exist, index.md will be used. This rule applies for every directory. If you want a file list of a directory, use inline Python and pathlib for that.
Get started
These are instructions for USING Dreamii, not to modify it.
python3 -m venv .venv
source .venv/bin/activate
pip install git+https://molodetz.nl/retoor/dreamii.git
echo "# My first dreamii site" > index.md
dreamii serve 7331
Develop with Dreamii
Just clone the repository and run install.
git clone https://molodetz.nl/retoor/dreamii.git
# Create virtual environment and install dependencies.
make install
# Run appliction within environment.
make run
Technologies used for creating this project
- Python3 as programming language.
- aiohttp for server.
- Jinja2 for templating.
- dataset for database.
Performance
This project runs using the default aiohttp server. If you want to use another server, see the aiohttp documentation. There are several supported. But Dreamii is by default good enough for thousands of requests per second. For the sake of usability, caching is not enabled. Every change to the site will be live directly.
Using markdown
Markdown files can be used as template files. They can be used for creating article content. You can also use markdown to create a static site. Rendering syntax for a specific language is done the same way as your used to at github. For more information, see Markdown. Markdown files will use the content block of the _base.html template if it exists.
Python inline support
It's possible to use inline py3 into your templates. You do this by starting {% py3 %} and ending {% endpy3 %}.
It has custom usable commands like shell executing that automatically encodes to HTML entities so it will be displayed properly.
Example shell execution
This example will print the output of the ps aux command. stderr is set to True so the result of the function will be stderr since that's the file descriptor that ps aux uses. output is set to False because it will directly render to the template if enabled. We want to print the output using one line of code between <pre> and </pre>.
{% py3 %}
print(
"<pre>",
system("ps aux", output=False, stderr=True),
"</pre>"
)
{% endpy3 %}
Example database usage
See here an example of a visitor counter on your website. This is all you have to do. It's a persistent database. No configuration required! For more information how to use the database, visit the dataset documentation.
{% py3 %}
def increment(counter_name="default")
counter = dreamii.db["counter"].find_one(counter_name=counter_name)
if not counter:
counter = {"count":0,"counter_name":"main_counter"}
counter["count"] += 1
dreamii.db["counter"].upsert(counter,["counter_name"])
return counter["count"]
print(f"<p>This page had been visited {counter()} times.</p>")
{% endpy3 %}
Hidden files
Files prefixed with _ or . will not be displayed or rendered by Dreamii. This is for security and it is a convenient way to mark base templates.
Base template
You can use any template you want as a base template but _base.html is special since it will be used for markdown templates by default if it exists. If you want to use it for markdown, ensure that a content block named markdown is available.
Example base template
<html>
<head>
<title>{% block title %}My site{% block title %}</title>
</head>
<body>
{% block html %}{% endblock %}
{% block markdown %}{% endblock %}
</body>
</html>
Use template for HTML
In this example we will be using the example base template mentioned above. We will use _base.html as our base template and overide the block named html with our content.
{% extends "_base.html" %}
{% block html %}
<h1>This is the page title!</h1>
<p>This is a paragraph</p>
{% endblock %}
Remember, you can use any file as base template.
| src | |
| .gitignore | |
| index.md | |
| main.py | |
| Makefile | |
| pyproject.toml | |
| README.md |