Embedding and including
=======================

Embedding
---------

An Almoststatic page is composed of a list of widgets arranged vertically,
with each subsequent widget appearing below the previous one.

However, this structure may not always suffice. There are instances where there
is a need to embed a widget within another. For example, in a tabbed or
accordion content, you may need to include an image row or some other widget.
Additionally, you might want to arrange contents in columns, necessitating the
embedding of contents in each column.

Almoststatic utilizes a recursive algorithm that makes it easy to achieve such
embedding. For instance, you can embed an accordion within a tabbed:

::

  - type: tabbed
    id: my_tab
    tabs:
      - label: tab1
        text: |
          ## tab 1
          Simple text

      - label: tab2
        text:
          content:
            - type: accordion
              id: fisa1
              cards:
                - button: "Card 1"
                  text: |
                    Text1
                - button: "Card 2"
                  text:
                    content:
                      - type: image_row
                        image: landscape1.jpg
                        text: |
                          my lorem content
                - button: "Card 3"
                  text: |
                    Text3

As illustrated, you can have an accordion within a tabbed, and an image_row
within the accordion.

Moreover, embedding can be nested at each level, with the nesting limit being
determined by the desired result quality.

To achieve this, simply place a ``content`` field list into the ``text`` field.

Almoststatic offers two other powerful methods for embedding contents into the
``text``. By using the ``embed`` and ``particle`` commands, you can insert
widgets wherever needed.

::

  content:
    - type: text_html
      text: "{{embed(page.txt1)}}"

    - type: text_html
      text: "{{particle('txt2')}}"

  txt1:
    - type: text_html
      text: My embedded content

  particles:
    - type: text_html
      id: txt2
      text: My particle

The choice between particle and embed is a matter of preference. ``particle`` is
clean and tidy, while ``embed`` can be more powerful.

Including
---------

Everything achievable with embedding can also be done with including.

Nested embedding on long pages might be challenging to maintain and keep organized.
For instance, there could be long text that is convenient to keep separated or
contents that should be present in multiple pages.

For these reasons, pages can be split into page and inclusion files:

::

  - type: tabbed
    id: my_tab
    tabs:
      - label: tab1
        text:
          include: include/page1/mytext.md

      - label: tab2
        text:
          include: include/page1/accordion.yaml

      - label: tab3
        text:
          include: include/page1/mytext.html

  - type: include
    file: include/page1/rest_of_page.yaml

In this example, the page is split into a page and inclusions. The keyword
``include`` is placed within the ``text`` keyword. Additionally, a special
widget called ``include`` can be used outside other widgets.

Inclusion files can be stored anywhere within the ``content`` folder except the
``pages`` folder, which is reserved for URL pages.

Almoststatic recognizes three types of inclusion file extensions: ``*.html``
for plain HTML files, ``*.md`` for Markdown files, and ``*.yaml`` for files
with a list of widgets.

As with embeddings, included files can have nested inclusions and embeddings.
The only limit is the quality of the result.