Spiega documentation

Article: org_files

What spiega is about

home imprint | privacy

present documentation

sabeiro

2026-06-23 Tue 00:00

Created: 2026-06-29 Mon 10:44

present this documentation

The documentation is made with mardown and .html files. We need to convert those files into a public documentation.

.html files are really versatile and can export to many other formats.

pdf
using LaTeX or postscript
html
with different exporting options
html reveal
mainly using reveal.js with reveal_custom.css
html slides
my custom scripts slide.js and slide.css

This file will be outputted as blog post or slides.

exporting

We started with many tools and we tried to minimize the dependencies so over time I removed the dependencies from tools like `markdown` and `pandoc`. I rather use my own header and footer templates In emacs.el we define most of the configurations and load the libraries. In reveal_config.html we have the additional configurations for export.

conversion scripts

Each website uses different scripts

spiega
technical blog
viudi
music website
blender_twin
project docs
foto
photography website
viaggi
travel website
scritti
personal blog

Where I built custom lisp and python files for tag manipulations.

.html publish

.html files allow the publishing option as defined in emacs.el where I can set a project and the publishing directory. All the .html files in the `base-directory` will be converted into the `publishing-directory` and the pictures will be copied.

(setq org-publish-project-alist
      '(("blender_twin"
         :base-directory "~/lav/src/blender_twin/docs/plan/"
         :publishing-directory "~/lav/siti/spiega/a/"
         :publishing-function roam-publication-wrapper
         :recursive t
         :html-head "<link rel=\"stylesheet\" href=\"static_html//css/org.css\" type=\"text/css\"/>\n"
         )
        ("images"
         :base-directory "~/lav/src/blender_twin/docs/f/"
         :base-extension "jpg\\|gif\\|png\\|svg"
         :recursive t
         :publishing-directory "~/lav/siti/f/"
         :publishing-function org-publish-attachment)))

emacs reveal slides

Emacs has many packages to convert .html into html + reveal.js, the most common is org-reveal but I tested org-re-reveal, emacs-reveal, oer-reveal, ox-reveal and they all cause headaches.

I had to pick manually select files from reveal.js and put them in the same order in the folder reveal/ with the same relative paths.

I tend to prefer `org-reveal` which has least dependencies.

TODO export file

I need to figure out how to change filename (add _slide) and how to move it to another directory

script

We use one command to export this file to reveal.js and move it to the final folder.

(org-reveal-export-to-html)
;;(org-re-reveal-export-to-html)
documentation_present.html
mv documentation_present.html ~/lav/siti/spiega/a/documentation_present_slide.html
#firefox http://localhost/spiega/a/documentation_present_slide.html

TODO oer package

Here we test the oer package

(use-package oer-reveal-publish)
(oer-reveal-setup-submodules t)
(oer-reveal-generate-include-files t)
(oer-reveal-publish-setq-defaults)
(setq oer-reveal-publish-babel-languages '((dot . t) (emacs-lisp . t))
      org-publish-project-alist
      (list (list "img"
                  :base-directory "~/lav/siti/blender_twin/"
                  :base-extension "png"
                  :publishing-function 'org-publish-attachment
                  :publishing-directory "~/lav/siti/f/f_twin/")))
img :base-directory ~/lav/siti/blender_twin/ :base-extension png :publishing-function org-publish-attachment :publishing-directory ~/lav/siti/f/f_twin/

wrap in tags

(use-package wrap-region)
(wrap-region-add-wrapper "<div class=\"r-stack\">" "</div>")

(lambda (arg) (interactive p) (wrap-region-trigger arg <div class=“r-stack”>))

convert folder

We mainly use following script to convert the documentation.

(org-publish-current-project)
#rm ~/lav/siti/spiega/a/*
cd $HOME/lav/src/spiega
bash ./script/convert.sh
/home/sabeiro/lav/siti/blender_twin//blog/agentic_usage.html
/home/sabeiro/lav/siti/blender_twin//blog/architecture.html
/home/sabeiro/lav/siti/blender_twin//blog/blender-mcp.html
/home/sabeiro/lav/siti/blender_twin//blog/blender_mcp_usage.html
/home/sabeiro/lav/siti/blender_twin//blog/debug_mode.html
/home/sabeiro/lav/siti/blender_twin//blog/documentation_conversion.html
/home/sabeiro/lav/siti/blender_twin//blog/editor_plugins.html
/home/sabeiro/lav/siti/blender_twin//blog/emacs_configuration2.html
/home/sabeiro/lav/siti/blender_twin//blog/emacs_configuration.html
/home/sabeiro/lav/siti/blender_twin//blog/emacs_ollama.html
/home/sabeiro/lav/siti/blender_twin//blog/emacs_workflow.html
/home/sabeiro/lav/siti/blender_twin//blog/esp32-iot-camera.html
/home/sabeiro/lav/siti/blender_twin//blog/file_operations.html
/home/sabeiro/lav/siti/blender_twin//blog/gptel_integration.html
/home/sabeiro/lav/siti/blender_twin//blog/implementation_diagram.html
/home/sabeiro/lav/siti/blender_twin//blog/ollama_integration.html
/home/sabeiro/lav/siti/blender_twin//blog/platformio_mode.html
/home/sabeiro/lav/siti/blender_twin//blog/project_details.html
/home/sabeiro/lav/siti/blender_twin//blog/project_packages.html
/home/sabeiro/lav/siti/blender_twin//blog/project_topology.html
/home/sabeiro/lav/siti/blender_twin//blog/svg_to_3d_blender.html
/home/sabeiro/lav/siti/blender_twin//blog/unified_view.html
/home/sabeiro/lav/siti/blender_twin//blog/agent_call.html
/home/sabeiro/lav/siti/blender_twin//blog/blender_twin.html
/home/sabeiro/lav/siti/blender_twin//blog/blender_twin_plan.html
/home/sabeiro/lav/siti/blender_twin//blog/blender_twin_stack.html
/home/sabeiro/lav/siti/blender_twin//blog/blender_twin_tasks.html
/home/sabeiro/lav/siti/blender_twin//blog/camera_esp32.html
/home/sabeiro/lav/siti/blender_twin//blog/microcontroller.html
/home/sabeiro/lav/siti/blender_twin//blog/sitemap.html
###        markdown/agent_workflow.html
###        markdown/documentation_present.html
###        markdown/multimedia_utils.html
/home/sabeiro/lav/siti/spiega/a/tmp.html