present documentation
work with tech

So I need to run the mcp server with transport http:

cd ~/lav/src/blender_twin/deploy/mcp_client/
#bash ./blender_local_client.sh &
cd $HOME/lav/src/blender_twin/deploy/mcp_client/blender_mcp_example_code/mcp/blmcp/ 
#python3 -m blmcp
uv --directory $HOME/lav/src/blender_twin/deploy/mcp_client/blender_mcp_example_code/mcp run blender-mcp --transport http --port 9191 &

I then need a container as defined in docker_compose.yml to create a bridge between the host and the containers within docker network.

blender-mcp-bridge:
  image: alpine/socat:latest
  container_name: blender-mcp-bridge
  network_mode: "host"
  command: TCP-LISTEN:19191,fork,reuseaddr TCP:127.0.0.1:9191
  restart: unless-stopped

I can then work on a script create_animation.py or let an LLM test the blender code without exiting the container.

Mermaid produces svg files which are loaded in blender apart from text which is not recognized. For that we created a script text2svg.py to load each text tag, load a font and create a path around that text. We apply as well some grouping logic so the import in blender is smoother.

cd ~/lav/src/spiega/script/
python3 text2svg.py ~/lav/siti/f/f_twin/arch_diagram.svg
mv output.svg ~/VideoProd/in_prog/graph/arch_dia.svg

File processed: /home/sabeiro/lav/siti/f/f_twin/arch_diagram.svgresults in output.svg

Create a slideshow from folders of images galery_show.py.

python3 ~/lav/src/malastro/media/galery_show.py

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.

We can visualize the current export options with:

[C-c C-e t]

#+TITLE:       the title to be shown (default is the buffer name)
#+AUTHOR:      the author (default taken from user-full-name)
#+DATE:        a date, an Org timestamp120, or a format string for format-time-string
#+EMAIL:       his/her email address (default from user-mail-address)
#+DESCRIPTION: the page description, e.g. for the XHTML meta tag
#+KEYWORDS:    the page keywords, e.g. for the XHTML meta tag
#+LANGUAGE:    language for HTML, e.g. ‘en’ (org-export-default-language)
#+TEXT:        Some descriptive text to be inserted at the beginning.
#+TEXT:        Several lines may be given.
#+OPTIONS:     H:2 num:t toc:t \n:nil @:t ::t |:t ^:t f:t TeX:t ...
#+BIND:        lisp-var lisp-val, e.g.: org-export-latex-low-levels itemize
               You need to confirm using these, or configure org-export-allow-BIND
#+LINK_UP:     the ``up'' link of an exported page
#+LINK_HOME:   the ``home'' link of an exported page
#+LATEX_HEADER: extra line(s) for the LaTeX header, like \usepackage{xyz}
#+EXPORT_SELECT_TAGS:   Tags that select a tree for export
#+EXPORT_EXCLUDE_TAGS:  Tags that exclude a tree from export
#+XSLT:        the XSLT stylesheet used by DocBook exporter to generate FO file

The options we have are:

H:         set the number of headline levels for export
num:       turn on/off section-numbers
toc:       turn on/off table of contents, or set level limit (integer)
\n:        turn on/off line-break-preservation (DOES NOT WORK)
@:         turn on/off quoted HTML tags
::         turn on/off fixed-width sections
|:         turn on/off tables
^:         turn on/off TeX-like syntax for sub- and superscripts.  If
you write "^:{}", a_{b} will be interpreted, but
the simple a_b will be left as it is.
-:         turn on/off conversion of special strings.
f:         turn on/off footnotes like this[1].
todo:      turn on/off inclusion of TODO keywords into exported text
tasks:     turn on/off inclusion of tasks (TODO items), can be nil to remove
all tasks, todo to remove DONE tasks, or list of kwds to keep
pri:       turn on/off priority cookies
tags:      turn on/off inclusion of tags, may also be not-in-toc
<:         turn on/off inclusion of any time/date stamps like DEADLINES
*:         turn on/off emphasized text (bold, italic, underlined)
TeX:       turn on/off simple TeX macros in plain text
LaTeX:     configure export of LaTeX fragments.  Default auto
skip:      turn on/off skipping the text before the first heading
author:    turn on/off inclusion of author name/email into exported file
email:     turn on/off inclusion of author email into exported file
creator:   turn on/off inclusion of creator info into exported file
timestamp: turn on/off inclusion creation time into exported file
d:         turn on/off inclusion of drawers

A typical syntax:

#+OPTIONS:     H:2 num:t toc:t \n:nil @:t ::t |:t ^:t f:t TeX:t ...

(org-insert-export-options-template)

We use multiple scripts to export, convert and publish the org files into slides, blog articles and pages: org-export.

• org-export-**.el

An exhaustive guide.

> export iframe

We can add css style in the page

References ref1, ref2, ref3, ref4, ref5, ref6, ref7

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

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

In case run a webserver

cd ~/lav/siti/blender_twin
python3 -m http.server

Copy default thumbnail if no other is provided

cd ~/lav/siti/f/f_stage
for i in ~/lav/src/spiega/article/* ;
do
    titN1=${i%.org}
    titN=${titN1##*/}
    thumbF=thumb_$titN.png
    if [ ! -f $thumbF ]; then
        echo $titN
        cp thumb_spiega.png $thumbF
    fi
done

Emacs has many packages to convert .org 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.

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

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)

mv documentation_present.html ~/lav/siti/spiega/a/documentation_present_slide.html
#firefox http://localhost/spiega/a/documentation_present_slide.html

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/")))

(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”>))

We want to create open graph descriptions and

	<!-- Open Graph -->
<meta property="og:title" content="technical blog">
<meta property="og:description" content="technical blog, a collection of articles/post written during 17y of career spanning over 3k3 source code files and 2k images">
<meta property="og:url" content="https://intertino.it/spiega/a/spiega.html">
<meta property="og:image" content="https://intertino.it/f/f_stage/module_library_small.png">

cd ~/lav/siti/f/f_stage/
for i in ~/lav/src/spiega/markdown/*.org;
do
    titN1=${i%.org}
    titN=${titN1##*/}
    cp module_library_small.png thumb_$titN.png
done

There are multiple guides with many different outcomes:

systemcrafters

We mainly use following script to convert the documentation.

(org-publish-current-project)

#rm ~/lav/siti/spiega/a/*
#rm ~/lav/siti/scritti/p/*
cd $HOME/lav/src/spiega
bash ./script/convert.sh

elogio noia
/home/sabeiro/lav/siti/scritti//a/elogio_noia.html

Here we test hugo which is nicely integrated with emacs and org-mode.

(use-package ox-hugo) (setq org-hugo-base-dir “~/lav/src/spiega/hugo”) (setq org-hugo-default-section-directory “post”)

#+hugo_base_dir:
export HUGO_BASE_DIR="~/lav/src/spiega/hugo/"

cd ~/lav/src/spiega/
hugo new project cios
cd quickstart
git init
git submodule add https://github.com/gohugo-ananke/ananke themes/ananke
echo "theme = 'ananke'" >> hugo.toml
hugo server

A wordpress approach:

(use-package org2blog) ;;uses wordpress

We want to create an index file from table of content

(defun org-toc ()
  (interactive)
  (let ((files (f-entries "." (lambda (f) (f-ext? f "org")) t))
    (headlines '())
    choice) 
    (loop for file in files do
      (with-temp-buffer 
        (insert-file-contents file) 
        (goto-char (point-min))
        (while (re-search-forward org-heading-regexp nil t)
          (cl-pushnew (list
               (format "%-80s (%s)"
                   (match-string 0)
                   (file-name-nondirectory file))
               :file file
               :position (match-beginning 0))
              headlines))))
    (setq choice
      (completing-read "Headline: " (reverse headlines)))
    (find-file (plist-get (cdr (assoc choice headlines)) :file))
    (goto-char (plist-get (cdr (assoc choice headlines)) :position))))

Here we use two main libraries

reveal

reveal.js example org to reveal

custom

org-export-reveal.el for batch processes run in convert.sh

There are multiple options to turn org files into reveal slides

custom

org-export-reveal.el and reveal_config for batch processes run in convert.sh

(require 'ox-publish)
(use-package ox-reveal)
(setq org-reveal-root "../reveal/")
(setq org-re-reveal-root "../reveal/")
(setq org-reveal-hlevel 1) 
(use-package oer-reveal)
(setq oer-reveal-publish-org-publishing-functions
      '(oer-reveal-publish-to-reveal))
(setq org-html-toc nil
      org-html-footnotes-in-header-file nil
      org-html-footnotes-after-body nil
      org-html-footnotes-as-uid t
      org-export-with-broken-links t
      org-export-with-toc nil
      org-export-with-section-numbers nil
      org-export-with-sub-superscripts nil
      org-html-verbatim "verbatim"
      org-use-sub-superscripts nil
      org-html-wrap-src-lines t
      org-html-prefer-user-labels t
      org-export-babel-evaluate nil 
      org-html-footer nil
      )

Here we use (org-tree-slide-mode) which basically displays and org file as slides. Navigation:

change section

[C-<] [C->]

show content

[C-x s c]

presets

simple

(org-tree-slide-simple-profile)

presentation

(org-tree-slide-presentation-profile)

narrow

no todos (org-tree-slide-narrowing-control-profile)

timer

(org-tree-slide-play-with-timer)

(use-package org-tree-slide
  :custom (org-image-actual-with nil))
(global-set-key (kbd "<f8>") 'org-tree-slide-mode)
(global-set-key (kbd "S-<f8>") 'org-tree-slide-skip-done-toggle)
(setq org-tree-slide-in-effect t
      org-tree-slide-activate-message "presentation started"
      org-tree-slide-deactivate-message "presentation ended"
      org-tree-slide-header t
      org-tree-slide-breadcrumbs " // "
)           

We can show the images in the file: (org-toggle-inline-images)

emacs has a lot of publishing options but in some cases I need a really custom design and therefore I strip header and footer from the html and append my own. We have a bash file for that convert_slide.sh. I need as well to convert the mermaid svg graph into a format blender can import which means first of all to convert the plain text into path which is accomplished by text2svg. This script tries as well to rename path ids to allow easier grouping into blender.

cd $HOME/lav/src/spiega/script/
bash ./convert.sh 
#bash ./text2svg.sh

###        /home/sabeiro/lav/src/spiega/article//documentation_present.org

We need to wrap the two columns into a div

We need to build an org-processor and a non-tech-user UI for editing some labels

map

into a defined semantic model or knowledge graph. Hugo could remain the employee-facing interface, while the graph and retrieval layer support relationships and semantic search.

sync

decide how changes are synchronized

access

tech users to access org-repository. UI users for curated documentation, project views, task summaries, and semantic search.

labels

sensitive content should be filtered out or enforced through query-time permissions

pipeline

Org repo → parser and validation → knowledge graph → role-aware internal web UI

semantic search

current task views, relationship navigation, and role-aware results

permissions

a narrowly scoped update API for employee-editable fields such as task status or approved labels

validation

updates would be validated, written back to Org, and then re-indexed into the knowledge graph and search layer

collision

server-authoritative document model, real-time synchronization, user presence, version history, and conflict handling—often through operational transformation or CRDT-style techniques

change review

submit changes only to approved properties or tags through the UI; the service validates the change, records the user and timestamp, applies it to Org through one write path, and re-indexes the graph and search projections

A draft of architecture would be:

repo

where all the org-files are stored

linter

a consistency check on information (end-date > start-date…)

commit

a series of allowed changes and permissions

sensitivity

sensitivity labels (inherit)