.. Almoststatic documentation master file, created by
   sphinx-quickstart on Mon Jul 12 15:58:10 2021.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

.. image:: /_static/Almoststatic.png
    :alt: Almoststatic
    :align: center
    :target: https://gitlab.com/claudio.driussi/almoststatic

Welcome to Almoststatic's documentation!
========================================

Almoststatic is a static sites and web pages generator engine using
`Jinja2 template system <https://jinja.palletsprojects.com/>`_ .It can be
integrated with `Flask <https://flask.palletsprojects.com/>`_ apps to serve
static contents on dynamic sites or used only for static sites development.

Pages are declared in `yaml <https://yaml.org/>`_ files and rendered with Jinja2
template files, the html contents can be written in `markdown <https://www.markdownguide.org/>`_
markup language or in plain html. "content" folder contains all data needed to
do the job, the "config.yaml" is used to share global parameters and to setup
configuration.

It is roughly inspired by `Hugo <https://gohugo.io/>`_ static site generator,
but it differs in many ways.

Why
---

There are many static site generators such as `Next.js <https://nextjs.org/>`_,
`Hugo <https://gohugo.io/>`_ or `Jekyll <https://jekyllrb.com/>`_, but you
can prefer Almostatic because:

- **It's perfect for pythonist.** It uses Jinja2 and Flask which are widely
  used by python community, so you don't need to learn other programming
  languages or template engines.

- **It's easy!** In fact the rules are very few and this mean few things to
  learn and great flexibility.

- **It's versatile.** It's engine has a powerful recursive system for embedding
  and including contents. This helps you to build rich contents and also to split
  them in small pieces called *"widgets"* easier to maintain, (see :doc:`pages`).

- **You can deliver static and dynamic contents at same time.** With Flask you
  can build your dynamic content and let Almoststatic to render the rest of page
  or the whole page, if it is full static.

- **Write static sites.** Static sites are composed only by text files and
  media contents. They are easy to deliver on the web, are secure by design,
  require less maintenance and resources and are faster. If you have no need for
  dynamic contents, with **Almoststatic** you can write all pages as static.

- **Not only for pythonists.** Basic knowledge of python is needed, but once
  your developer environment is ready, Almoststatic lets you to focus on
  writing yaml and markdown's contents and to create your own widgets in html
  and Jinja2.

Status of project
-----------------

Almoststatic is now in beta. It should be stable enough to produce right
results, but it wasn't used enough to put him in stable status.

Almoststatic is a young project, so at the moment there are no themes ready to
use but we are developing a theme with some beautiful widgets ready to production.
See `Fullstep theme <https://gitlab.com/almoststatic-themes/fullstep/>`_ and
follow the tutorial.

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   quickstart.rst
   structure.rst
   pages.rst
   embedding.rst
   processors.rst
   templates.rst
   static.rst
   api.rst
   changelog.rst