archsight 0.4.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66e3a2aa9223a9583edf06749e12bafe346bfd562570d299795f2334510ed36a
-  data.tar.gz: 52a7997e394247a86da162fb4015d97b755b2ac2fe69cfadd758f6d3e140c33b
+  metadata.gz: f7ada570ca5a5647d0cb9dc9f23b37d8adc9c0b6eff5420154c8ef3d30d9ea95
+  data.tar.gz: ba2e28e035b6d091fbfaeef71b0bc8d775f84c88541ecea0de86ba7d256bde42
 SHA512:
-  metadata.gz: adc6fb4fad180ae14920ecfbccebfb242c9b3d48bc6bfb196b645de67f4dc490e4922274175fa9f942cfe4d80a327b8a4cf171ad9ccc1edd195c5d283c636bba
-  data.tar.gz: e82af637b926e46db4b61c23269d8f5b630222b78f6e169d413b21aa2f12858cbc80cacbc8325ab1d550174e11fedc8ca1780489d025c3dabe5c1943d1fd887b
+  metadata.gz: 739c46f505dfa73125839be21c2f0baaba7b4ba2a98926ca449a2cf87088cbc2c910c6b016c67ac7905540430927f94f2dc1b0bdce29735aec1ab29857390d7c
+  data.tar.gz: c259164f01f0d14e47dc5bf7f25a572a1a519dcc92ca788f3191274df5b6e0fd4d3d90fcdc5bc253bca6b454db464aa6ab46eaffa1f5a7f515b000a307506324

data/Dockerfile

@@ -25,6 +25,10 @@ ENV GEM_HOME=/usr/local/bundle
 ENV GEM_PATH=/usr/local/bundle:/usr/local/lib/ruby/gems/4.0.0
 ENV PATH="/usr/local/bundle/bin:${PATH}"
 
+# PDF export (Archsight::Pdf): typst typesets the documents, rsvg-convert turns the diagrams into vector graphics,
+# graphviz draws the dependency graph of a resource
+RUN apk add --no-cache typst rsvg-convert font-liberation font-dejavu font-noto-emoji graphviz
+
 RUN mkdir -p /resources
 
 ENV ARCHSIGHT_RESOURCES_DIR=/resources

data/docs/configuration.md

@@ -37,6 +37,11 @@ that is set but empty counts as not set.
 | `jira.server` | `ARCHSIGHT_JIRA_SERVER` | Name of the Jira server as Confluence knows it (the `server` parameter of its Jira macro). Needed by the Confluence export when Confluence has more than one Jira server: without it the exported `{jira:KEY}` macros have no server and Confluence shows an error |
 | `jira.server_id` | `ARCHSIGHT_JIRA_SERVER_ID` | Id of that server (the `serverId` parameter). Copy both from the storage format of a Jira macro that already works in Confluence (page "Edit in storage format") |
 | `jira.token` | `ARCHSIGHT_JIRA_TOKEN` | Reserved, nothing uses it yet |
+| `pdf.typst` | `ARCHSIGHT_PDF_TYPST` | Path of the `typst` command that typesets the [PDF export](/doc/pdf-export), if it is not on the `PATH` |
+| `pdf.dot` | `ARCHSIGHT_PDF_DOT` | Path of Graphviz' `dot` command that draws the dependency graph in the [PDF export](/doc/pdf-export), if it is not on the `PATH`. Without it the PDF of a resource has no graph |
+| `pdf.timeout` | `ARCHSIGHT_PDF_TIMEOUT` | Seconds a PDF may take to typeset before it is cancelled. Default `60` |
+| `pdf.remote_images` | `ARCHSIGHT_PDF_REMOTE_IMAGES` | `false` stops the PDF export from fetching images that a page embeds by URL (default: fetched, public hosts only) |
+| `pdf.max_analyses` | `ARCHSIGHT_PDF_MAX_ANALYSES` | How many `![[Analysis/...]]` embeds one PDF may run (each can take as long as its own timeout). Default `5`; further ones are shown as a note |
 | `import.cache_root` | `ARCHSIGHT_IMPORT_CACHE_ROOT` | Where the GitHub, GitLab and repository imports clone repositories, and what importers of the resources repository get as `cache_root` / `ARCHSIGHT_CACHE_DIR`. Default `~/.cache/archsight/git`; an import's own `import/config/cacheRoot` wins, see [Importers of the Resources Repository](/doc/import#importers-of-the-resources-repository). Every import makes sure the clones are not indexed by Spotlight (macOS): an empty `.metadata_never_index` in `~/.cache/archsight`, or in the cache root when it is elsewhere |
 
 ## Command line

data/docs/diagram.md

@@ -145,6 +145,11 @@ hint for near misses), never silently ignored.
 | `link` | nodes, containers | `http(s)://…`, `mailto:…` or a relative URL |
 | `resource` | nodes, containers | a resource name (`Archsight:Web`) or `Kind/Name` (`ApplicationService/Archsight:Web`); see *Linking to resources* |
 | `extend` | nodes, containers | `true`, `false`; containers also `height` |
+| `anchor` | containers | `top`, `bottom`, `left`, `right`, `center` |
+
+`extend "height"` on a direct child of a `layer` grows it to its tallest sibling. Inside such a box (also through a `boundary` around a `stack`), a `stack` child carrying `extend "height"` takes the extra height and moves the ranks below it down, so e.g. a footer rank lines up across the columns. The child can be a `layer` too; its own `extend "height"` children then fill the layer's new height.
+
+`anchor` says where a container's content sits when its box grows: `bottom` (or `top`) when it is made taller, `right` (or `left`) when it is made wider, `center` for the middle. Default: top for `extend "height"`, centered otherwise. It is not inherited, and has no effect on a box whose room is taken by a stack child with `extend "height"`.
 | `shape` | leaves | `rectangle`, `circle`, `cylinder`, `pipe`, `actor`, `file`, `module` |
 | `gap` | containers | pixels (`40`), a percentage (`150%`) or a signed one (`+20%`, `-50%`) |
 | `ranks` | containers | `auto`, `on`, `down`, `right`, `off` |

data/docs/index.md.erb

@@ -8,6 +8,7 @@ Welcome to the Architecture Documentation System. This documentation covers how
 - [Configuration](/doc/configuration) - The configuration file and environment variables for tokens and URLs
 - [Query Syntax](/doc/search) - Search and filter resources
 - [Wiki Pages](/doc/pages) - Author markdown pages and arrange them in the sidebar tree
+- [PDF Export](/doc/pdf-export) - Download pages and resources as PDF, with a Config for the look
 - [Architecture Modeling](/doc/modeling) - How to model your architecture
 - [REST API Documentation](/docs/api) - JSON API for programmatic access
 - [Diagrams](/doc/diagram) - Render `.asd` diagram files to SVG

data/docs/pdf-export.md

@@ -0,0 +1,118 @@
+# PDF Export
+
+Every [page](/doc/pages) and every resource can be downloaded as a PDF. The document is typeset by [Typst](https://typst.app),
+so the server (or the machine running the CLI) needs the `typst` command; the container image has it, together with
+`rsvg-convert` (turns diagrams into vector graphics), `dot` of Graphviz (draws the dependency graph) and a few fonts.
+
+## Getting a PDF
+
+- **Web UI:** the **PDF** button next to **Edit** on a page or resource.
+- **API:** `GET /api/v1/pages/{name}/pdf` and `GET /api/v1/kinds/{kind}/instances/{name}/pdf`, see the [REST API documentation](/docs/api).
+  The response has an `ETag` that changes whenever the page, an image, a diagram or the template changes.
+  Query parameters: `template` (name of a pdf Config) and `draft=1` (watermark).
+- **CLI:** `archsight pdf <page>` or `archsight pdf Kind/Name`, with `-o file.pdf`, `--template` and `--draft`.
+
+Without `typst` the API answers `503` and the button shows the reason.
+
+## What is in the document
+
+- A **page** is typeset as written: headings, text, tables (with their alignment), task lists, code, images next to the page,
+  `asd` diagrams (as vector graphics), `[[links]]` (as their label), `{status:...}` (a coloured box), `{jira:KEY}` (a link
+  when `jira.issue_url` is set) and `{emoticon:...}`. Macros that need the running application (`{children}`) are left out.
+  Mermaid blocks and draw.io images cannot be drawn on the server: a note stands there (and the Mermaid source).
+- **Tables** have horizontal rules only: a stronger one under the header row and a light one under every other row, no frame
+  and no vertical lines, in the muted colour of the Config; the first column is flush with the text.
+- **Live content is the data of the moment of the export**, as in the Confluence export:
+  - `![[View/Name]]` and ```` ```view ```` blocks are tables (title, number of items, repeated header row; long columns
+    share the width), `` ```requirements `` blocks are the requirements table.
+  - `![[Analysis/Name]]` runs the analysis and puts its sections (headings, text, tables, lists, messages) into the document.
+    An analysis runs for as long as its own `analysis/timeout` allows, so at most 5 run per document (`pdf.max_analyses`),
+    and a result is reused for a minute. A failed analysis shows its error.
+  - `![[Kind/Name]]` of another kind is the resource's description.
+  - Only an embed on a line of its own (or several, one per line) is content; inside a sentence it stays its name.
+  - What cannot be shown (unknown or ambiguous reference, an invalid view or requirements block) is a visible note in the
+    document, never blank space. Embeds inside an embedded description are not expanded again.
+- **Images by URL** (`![](https://...)`) are fetched by the server so they can go into the PDF. Only public hosts on https/http
+  are contacted (never loopback, private or link-local addresses, so the server cannot be used to reach the network
+  behind it), at most 10 MB and 10 seconds each, and only real png, jpeg, gif or webp files are used; otherwise the alt text
+  is shown. `pdf.remote_images: false` turns this off.
+- Any other **resource** becomes a generated document: its description, its properties, its relations and its
+  `architecture/diagram`, and its **dependency graph**, shown first, as on its page (the resources its relations lead to, two steps
+  deep, following its own layer and the one below it, nodes coloured by layer), drawn by `dot` in the direction, left to
+  right or top to bottom, in which it is larger on the page. A resource without
+  relations has no graph, and without `dot` the document is made without it. Properties are a label and value list (related annotations kept together; lists as "a, b";
+  multi-line and markdown values as sections of their own). Relations are shown in both directions, **Outgoing** (what this
+  resource points to) and **Incoming** (what points to it, read from the other side): the relation is named once, with the
+  kind next to it and the resources flowing in two columns, so a resource with many relations stays readable.
+
+## Steering the layout with tags
+
+Tags of the page (`tags:` in the frontmatter) or of a resource (`architecture/tags`):
+
+| Tag | Effect |
+|-----|--------|
+| `pdf:cover` | A cover page (logo band, title, id, version, date, owner) instead of the title block |
+| `pdf:toc` | A table of contents |
+| `pdf:landscape` | Landscape pages |
+| `pdf:draft` | A "draft" watermark on every page |
+| `pdf:no-graph` | Leave the dependency graph out of a resource's document |
+| `pdf:template:<name>` | Use the pdf Config `<name>` instead of `default` |
+| `version:<x>` | The document version in the header (else the page property `Version`, else `1`) |
+
+Further page data used by the layout: `title`, `owner` (else `author`), `updated` (else today), and the page properties
+`Document ID` (default `Kind/name`) and `Classification` (red marking in the footer, default from the template).
+
+## The look: Config
+
+A `Config` resource (layer *Other*) holds settings of a feature of the tool, kept with the model; `config/type` says
+which feature. The PDF export reads the Configs of type `pdf`: colours, fonts, logo and the text around the pages. The one
+named `default` is used for every document that does not name another (`pdf:template:<name>`); `brand`, `PDF:brand` and
+`Config:PDF:brand` all name the same Config. Without any a neutral look is used. A Config of another type is never used
+for the PDF, so every feature can have its own `default`. (The per-user file with tokens and URLs stays
+[`~/.config/archsight/archsight.yaml`](/doc/configuration).)
+
+```yaml
+apiVersion: architecture/v1alpha1
+kind: Config
+metadata:
+  name: Config:PDF:default
+  annotations:
+    config/type: pdf
+    pdf/color-primary: "#1f3a5f"
+    pdf/color-accent: "#2f7fd1"
+    pdf/logo: assets/logo.svg
+    pdf/logo-light: assets/logo-white.svg
+    pdf/footer-text: Generated with Archsight
+    pdf/classification: Internal
+    pdf/font-body: Open Sans
+    pdf/font-dir: assets/fonts
+spec: {}
+```
+
+| Annotation | Meaning |
+|------------|---------|
+| `config/type` | `pdf` for these settings |
+| `pdf/color-primary`, `-accent`, `-text`, `-muted`, `-ok`, `-warn`, `-danger` | Hex colours (`#rrggbb`) |
+| `pdf/font-body`, `-heading`, `-mono` | Font families, tried before the built-in fallbacks |
+| `pdf/font-dir` | Directory (relative to the resources directory) with font files (ttf, otf) that ship with the model |
+| `pdf/logo`, `pdf/logo-light` | svg or png, relative to the resources directory. `logo` is shown on white (page header), `logo-light` on the cover band |
+| `pdf/footer-text`, `pdf/classification` | Texts in the footer of every page |
+| `pdf/header-meta` | Parts of the header line: `id, version, date, owner` |
+| `pdf/lang` | Language of the fixed texts: `en` or `de` |
+| `pdf/paper`, `pdf/margin` | `a4`, `a5` or `us-letter`; horizontal margin such as `16mm` |
+
+Values are checked when they are loaded (and by `archsight lint`): something that is not a colour, a font name or a length is
+ignored and the default is used.
+
+## Seeing the look
+
+The page of a Config of type `pdf` shows its settings as they look (the colours, the fonts, the logo on white and on
+the cover band, the page settings) and, beside them, a **preview**: a fixed sample document (a cover page and a page with
+headings, a list, a quote, a table with status badges and code) typeset by the server with exactly these settings, one
+tab for the cover and one for the page. It shows the saved Config; after an edit the page typesets it again.
+The same sample is `GET /api/v1/kinds/Config/instances/{name}/preview` (`?part=cover` or `?part=page` for one page).
+
+## Settings
+
+`pdf.typst` (`ARCHSIGHT_PDF_TYPST`) is the path of the `typst` command if it is not on the `PATH`, `pdf.dot` (`ARCHSIGHT_PDF_DOT`) the same for `dot`, `pdf.timeout`
+(`ARCHSIGHT_PDF_TIMEOUT`) the seconds a document may take (default 60), `pdf.remote_images` (`ARCHSIGHT_PDF_REMOTE_IMAGES`) `false` to never fetch images by URL, `pdf.max_analyses` (`ARCHSIGHT_PDF_MAX_ANALYSES`) the number of analyses one document may run (default 5). See [Configuration](/doc/configuration).

data/lib/archsight/analysis/typst_renderer.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "../markdown"
+require_relative "../pdf/typst"
+require_relative "../pdf/markdown"
 require_relative "../diagram"
 
 module Archsight
@@ -10,20 +12,18 @@ module Archsight
     # All text is emitted as Typst string literals (`#"..."`) and structure as
     # function calls (`#strong[...]`), so no content can be mistaken for markup.
     class TypstRenderer
+      include Archsight::Pdf::Typst
+
       ROW_LIMIT = 10
       HEADING_OFFSET = 2 # section level 0 becomes a level-2 heading, the analysis name is level 1
-      LANGUAGE = /\A[A-Za-z0-9+#-]+\z/
       MESSAGE_FILL = { error: "rgb(\"#fde8e8\")", warning: "rgb(\"#fff3cc\")", info: "rgb(\"#ddeeff\")" }.freeze
-      SYMBOLS = {
-        ndash: "–", mdash: "—", hellip: "…", laquo: "«", raquo: "»", laquo_space: "« ", raquo_space: " »",
-        lsquo: "‘", rsquo: "’", ldquo: "“", rdquo: "”"
-      }.freeze
 
       PREAMBLE = <<~TYPST
         #set document(title: "Archsight analysis")
         #set page(paper: "a4", margin: 2cm, numbering: "1")
         #set text(size: 10pt)
         #show raw.where(block: true): it => block(fill: luma(245), inset: 8pt, radius: 3pt, width: 100%, it)
+        #set table(stroke: (x, y) => if y == 0 { (bottom: 0.7pt + luma(150)) } else { (bottom: 0.4pt + luma(220)) }, inset: (x, y) => (left: if x == 0 { 0pt } else { 6pt }, right: 6pt, y: 6pt))
       TYPST
 
       # @param results [Array<Archsight::Analysis::Result>]
@@ -31,10 +31,12 @@ module Archsight
       # @param template [String, nil] Typst file to import instead of the built-in layout. It must define
       #   `archsight-report` (a show rule for the document) and `analysis-result` (one call per analysis,
       #   with the data sections as a dictionary and the other sections as body).
-      def initialize(results, verbose: false, template: nil)
+      # @param full [Boolean] show every table row and list item, without the error backtrace of `verbose`
+      def initialize(results, verbose: false, template: nil, full: false)
         @results = results
         @verbose = verbose
         @template = template
+        @full = full
       end
 
       # @return [String] Typst source
@@ -44,6 +46,17 @@ module Archsight
         [PREAMBLE, title, summary, *@results.map { |result| render_result(result) }].join("\n")
       end
 
+      # One section of a result as Typst markup (nil for data that only templates use)
+      # @param heading_offset [Integer] added to the level of a heading section
+      def section(section, heading_offset: HEADING_OFFSET)
+        render_section(section, heading_offset)
+      end
+
+      # The error of a failed result as Typst markup
+      def error(result)
+        error_block(result)
+      end
+
       private
 
       def title
@@ -120,9 +133,9 @@ module Archsight
         lines.join("\n\n")
       end
 
-      def render_section(section)
+      def render_section(section, heading_offset = HEADING_OFFSET)
         case section[:type]
-        when :heading then "#heading(level: #{[section[:level] + HEADING_OFFSET, 6].min})[#{str(section[:text])}]"
+        when :heading then "#heading(level: #{[section[:level] + heading_offset, 6].min})[#{str(section[:text])}]"
         when :text then markdown(section[:content])
         when :table then table(section[:headers], section[:rows])
         when :list then list(section[:items])
@@ -139,15 +152,14 @@ module Archsight
 
       # A template produces a document to hand out, so it gets every row
       def full?
-        @verbose || !@template.nil?
+        @verbose || @full || !@template.nil?
       end
 
       def table(headers, rows)
         shown = full? ? rows : rows.first(ROW_LIMIT)
-        head = headers.map { |header| "[#strong[#{str(header)}]]" }
+        head = headers.map { |header| "[#text(weight: \"semibold\")[#{str(header)}]]" }
         cells = shown.flat_map { |row| headers.each_index.map { |i| "[#{str(row[i])}]" } }
-        out = "#table(columns: #{headers.size}, inset: 5pt, stroke: 0.5pt + luma(200), " \
-              "table.header(#{head.join(", ")}), #{cells.join(", ")})"
+        out = "#table(columns: #{headers.size}, table.header(#{head.join(", ")}), #{cells.join(", ")})"
         out += "\n\n#emph[#{str("...and #{rows.size - ROW_LIMIT} more rows")}]" if shown.size < rows.size
         out
       end
@@ -172,73 +184,8 @@ module Archsight
         [message_block(:error, "Diagram could not be rendered: #{e.message}"), raw(source, "asd")].join("\n\n")
       end
 
-      def raw(source, lang)
-        lang_arg = lang.to_s.match?(LANGUAGE) ? ", lang: #{lit(lang)}" : ""
-        "#raw(#{lit(source.to_s.chomp)}, block: true#{lang_arg})"
-      end
-
-      # A Typst string literal, for use as a function argument
-      def lit(text)
-        escaped = text.to_s.delete("\r").gsub(/[\\"]/) { "\\#{Regexp.last_match(0)}" }.gsub("\n", "\\n")
-        "\"#{escaped}\""
-      end
-
-      # A Typst string literal as markup, for use inside content
-      def str(text)
-        "##{lit(text)}"
-      end
-
-      # ---- markdown -> Typst
-
       def markdown(source, inline: false)
-        root = Archsight::Markdown.document(source).root
-        out = blocks(root.children)
-        inline ? out.gsub(/\n\n+/, " #linebreak() ") : out
-      end
-
-      def blocks(elements)
-        elements.filter_map { |node| block(node) }.join("\n\n")
-      end
-
-      def block(node)
-        case node.type
-        when :p then inlines(node.children)
-        when :header then "#heading(level: #{[node.options[:level] + 1, 6].min})[#{inlines(node.children)}]"
-        when :codeblock then raw(node.value, node.options[:lang])
-        when :blockquote then "#quote(block: true)[#{blocks(node.children)}]"
-        when :ul then "#list(#{node.children.map { |li| "[#{blocks(li.children)}]" }.join(", ")})"
-        when :ol then "#enum(#{node.children.map { |li| "[#{blocks(li.children)}]" }.join(", ")})"
-        when :hr then "#line(length: 100%)"
-        when :table then markdown_table(node)
-        when :blank, :html_element, :xml_comment then nil
-        else inlines(node.children) unless node.children.empty?
-        end
-      end
-
-      def markdown_table(node)
-        rows = node.children.flat_map(&:children)
-        cells = rows.map { |tr| tr.children.map { |td| "[#{inlines(td.children)}]" } }
-        width = cells.map(&:size).max || 1
-        "#table(columns: #{width}, inset: 5pt, stroke: 0.5pt + luma(200), #{cells.flatten.join(", ")})"
-      end
-
-      def inlines(elements)
-        elements.map { |node| inline(node) }.join
-      end
-
-      def inline(node)
-        case node.type
-        when :text then str(node.value)
-        when :em then "#emph[#{inlines(node.children)}]"
-        when :strong then "#strong[#{inlines(node.children)}]"
-        when :codespan then "#raw(#{lit(node.value)})"
-        when :a then "#link(#{lit(node.attr["href"])})[#{inlines(node.children)}]"
-        when :br then "#linebreak()"
-        when :entity then str(node.value.char)
-        when :smart_quote, :typographic_sym then str(SYMBOLS.fetch(node.value, node.value.to_s))
-        when :html_element then inlines(node.children)
-        else inlines(node.children)
-        end
+        Archsight::Pdf::Markdown.new(heading_offset: 1, diagram: method(:diagram)).render(source, inline: inline)
       end
     end
   end

data/lib/archsight/cli.rb

@@ -356,6 +356,43 @@ module Archsight
       exit 1
     end
 
+    desc "pdf TARGET", "Export a page or resource as PDF (needs typst)"
+    long_desc <<~DESC
+      Typesets a page (TARGET is its name) or any other resource (TARGET is Kind/Name) as a PDF with Typst, the same
+      document the PDF button of the web UI downloads. The look comes from the Config of type pdf named default (or --template),
+      the tags pdf:cover, pdf:toc, pdf:landscape, pdf:draft and pdf:template:<name> steer the layout. The typst command
+      is taken from the PATH, or from ARCHSIGHT_PDF_TYPST / `pdf.typst` in ~/.config/archsight/archsight.yaml.
+      See the PDF Export page of the documentation.
+    DESC
+    option :output, aliases: "-o", type: :string, desc: "Output file (default: <name>.pdf in the current directory)"
+    option :template, type: :string, desc: "Name of the pdf Config to use (default: the tag or `default`)"
+    option :draft, type: :boolean, default: false, desc: "Add the draft watermark"
+    def pdf(target)
+      configure_resources
+      require "archsight/database"
+      require "archsight/pdf"
+
+      db = Archsight::Database.new(Archsight.resources_dir, compute_annotations: false)
+      begin
+        db.reload!
+      rescue Archsight::ResourceError => e
+        display_error_with_context(e.to_s)
+        exit 1
+      end
+
+      kind, name = target.include?("/") ? target.split("/", 2) : ["Page", target]
+      resource = Archsight::Resources[kind] && (db.instance_by_kind(kind, name) || db.instance_by_alias(kind, name))
+      abort "Error: #{kind} '#{name}' not found" unless resource
+
+      document = Archsight::Pdf.document(db, resource, template: options[:template], draft: options[:draft])
+      file = options[:output] || document.filename
+      File.binwrite(file, Archsight::Pdf.compile(document))
+      puts "Wrote #{file}"
+    rescue Archsight::Pdf::Error => e
+      warn "Error: #{e.message}"
+      exit 1
+    end
+
     desc "module SUBCOMMAND", "Module analysis commands (e.g. module graph PATH)"
     subcommand "module", ModuleCLI
 

data/lib/archsight/diagram/graph/attributes.rb

@@ -27,13 +27,14 @@ module Archsight
         NODE = %w[label tint link resource extend].freeze
         LEAF_KINDS = %i[component application api database queue actor file].freeze
         LEAF = (NODE + %w[shape]).freeze
-        CONTAINER = (NODE + %w[gap ranks columns]).freeze
+        CONTAINER = (NODE + %w[gap ranks columns anchor]).freeze
         EDGE = %w[label style relation tint].freeze
         DATAFLOW = %w[label color].freeze
 
         EDGE_STYLES = %w[straight orthogonal].freeze
         LEAF_EXTEND = %w[true false].freeze
         CONTAINER_EXTEND = %w[true false height].freeze
+        ANCHORS = %w[top bottom left right center].freeze
 
         # `40` (pixels), `150%` (of the default), `+20%`/`-50%` (relative);
         # see `GapSpec`.
@@ -116,6 +117,7 @@ module Archsight
           when "tint" then check_value!(key, value, Tints.names, where, line)
           when "ranks" then check_value!(key, value, ranks_modes, where, line)
           when "extend" then check_value!(key, value, leaf?(block) ? LEAF_EXTEND : CONTAINER_EXTEND, where, line)
+          when "anchor" then check_value!(key, value, ANCHORS, where, line)
           when "gap" then check_format!(key, value, GAP_FORMAT, "a pixel count (40), a percentage (150%) or a signed one (+20%, -50%)", where, line)
           when "link" then check_link!(value, where, line)
           when "resource" then check_resource!(value, block, where, line)

data/lib/archsight/diagram/graph/node.rb

@@ -130,11 +130,28 @@ module Archsight
         # `extend "height"` on a direct child of a `layer` grows that
         # child's box to its tallest sibling's height, leaving its own
         # content top-aligned where it already sits. Never inherited --
-        # only the node carrying the attr is affected.
+        # only the node carrying the attr is affected. In a `stack` inside such a
+        # grown box it absorbs the extra height instead (see
+        # `Expander#grow_height`).
         def extend_height?
           attrs["extend"] == "height"
         end
 
+        # Where this container's content sits when its box grows by `extra`
+        # along `axis`: the `anchor` attr (`top`/`bottom` for height,
+        # `left`/`right` for width, `center`), else `default`. Returns how
+        # far to shift the children (0 = leading edge, `extra` = trailing).
+        # Never inherited; a value for the other axis is ignored.
+        def anchor_shift(axis, extra, default:)
+          value = attrs["anchor"]
+          value = default.to_s unless (axis == Axis::HEIGHT ? %w[top bottom center] : %w[left right center]).include?(value)
+          case value
+          when "top", "left" then 0.0
+          when "bottom", "right" then extra.to_f
+          else extra / 2.0
+          end
+        end
+
         def link
           attrs["link"]
         end

data/lib/archsight/diagram/layout/expander.rb

@@ -97,29 +97,101 @@ module Archsight
               # their own (now wider) box -- explaining a rank that visibly
               # spills outside its container despite matching its siblings'
               # width exactly.
-              center = own_target / 2.0
+              #
+              # The room they get is the *inner* one -- the target minus the
+              # node's own padding (and title bar), as in the single-child
+              # case below -- or they would sit flush on its border; the
+              # centerline is the middle of that inner area.
+              inner = own_target - inset(node, axis)
+              center = leading_inset(node, axis) + (inner / 2.0)
               node.children.each do |c|
-                expand(c, axis, own_target, inherited: extend)
+                expand(c, axis, inner, inherited: extend)
                 axis.set_position(@boxes[c.id], center)
               end
             end
             return
           end
 
-          recenter_children(node, axis, extra / 2.0) if extra.positive?
+          recenter_children(node, axis, node.anchor_shift(axis, extra, default: :center)) if extra.positive?
 
           return unless node.children.length == 1
 
           expand(node.children.first, axis, own_target - inset(node, axis), inherited: extend)
         end
 
+        # `extend "height"`: grows `node` to `target` height keeping its
+        # content top-aligned (or at its `anchor`), then hands the extra room to whatever inside
+        # can absorb it -- a `stack` child carrying `extend "height"`
+        # itself (the first such one in a stack's column gets all of it, and
+        # the ranks below it move down, so e.g. a footer rank lines up
+        # across columns), reached through single-child wrappers such as a
+        # `boundary` around a `stack`.
+        def grow_height(node, target)
+          box = @boxes[node.id]
+          extra = target - box.height
+          return if extra <= 0
+
+          box.height = target
+          return if node.children.empty?
+
+          # An explicit `anchor` decides where the content sits; otherwise a
+          # stack (or a wrapper around one) hands the room to its
+          # `extend "height"` child, and anything else stays top-aligned.
+          delta = node.anchor_shift(Axis::HEIGHT, extra, default: :top)
+          return recenter_children(node, Axis::HEIGHT, delta) if delta.positive?
+
+          if node.layer?
+            fill_layer(node, extra)
+          elsif node.children.length == 1
+            inner = node.children.first
+            grow_top_aligned(inner, extra) if inner.stack? || inner.extend_height?
+          elsif node.stack?
+            absorb_in_stack(node, extra)
+          end
+        end
+
         private
 
+        # A grown `layer`'s `extend "height"` children fill the new height
+        # too (they were only matched to their tallest sibling before).
+        def fill_layer(node, extra)
+          room = @boxes[node.id].height - inset(node, Axis::HEIGHT)
+          node.children.select(&:extend_height?).each do |c|
+            grow = room - @boxes[c.id].height
+            grow_top_aligned(c, grow) if grow.positive? && extra.positive?
+          end
+        end
+
+        # Grows a child by `extra` keeping its top edge where it is (box
+        # positions are centers, so the center moves down by half of it).
+        def grow_top_aligned(node, extra)
+          grow_height(node, @boxes[node.id].height + extra)
+          @boxes[node.id].y += extra / 2.0
+        end
+
+        # Gives `extra` to the first child of the `stack` `node` marked
+        # `extend "height"`, and shifts every later rank down by it.
+        def absorb_in_stack(node, extra)
+          ordered = node.children.sort_by { |c| @boxes[c.id].y }
+          index = ordered.index(&:extend_height?)
+          return unless index
+
+          grower = ordered[index]
+          grow_top_aligned(grower, extra)
+          ordered[(index + 1)..].each { |c| @boxes[c.id].y += extra }
+        end
+
         # How much of a container's size on `axis` is reserved by its own
         # padding (and, on the height axis, its title bar) rather than
         # available to a single child filling it -- the node's own
         # `layout_padding`/`layout_title_height` (nothing, for an anonymous
         # `layer`/`stack`, since it renders no box to pad).
+        # The padding (plus title bar, on the height axis) before the content.
+        def leading_inset(node, axis)
+          padding = node.layout_padding(@theme)
+          axis == Axis::HEIGHT ? padding + node.layout_title_height(@theme) : padding
+        end
+
         def inset(node, axis)
           padding = 2 * node.layout_padding(@theme)
           axis == Axis::HEIGHT ? padding + node.layout_title_height(@theme) : padding

data/lib/archsight/diagram/layout/rank_arranger.rb

@@ -74,7 +74,9 @@ module Archsight
         def arrange_layer(group, children)
           max_height = children.map { |c| @boxes[c.id].height }.max
           children.each do |c|
-            @boxes[c.id].height = max_height if !c.leaf? && c.extend_height?
+            next if c.leaf? || !c.extend_height?
+
+            Expander.new(@boxes, theme: @theme).grow_height(c, max_height)
           end
 
           gap = group.gap(@theme.sibling_gap)

data/lib/archsight/markdown.rb

@@ -14,9 +14,25 @@ module Archsight
     # Raw HTML whose text is kept as it is
     VERBATIM = %w[pre code script style textarea].freeze
 
+    # Fenced code and inline code, which are left as written
+    CODE = /(^[ \t]*(?:`{3,}|~{3,}).*?^[ \t]*(?:`{3,}|~{3,})[ \t]*$|`+[^`\n].*?`+)/m
+    WIKI_LINK_PIPE = /\[\[[^\]\n]*\]\]/
+
     def self.document(text, **)
-      Kramdown::Document.new(text.to_s, **OPTIONS, **)
+      Kramdown::Document.new(protect_wiki_link_pipes(text.to_s), **OPTIONS, **)
+    end
+
+    # Kramdown reads every line with a `|` as a table row, which would cut `[[Target|label]]` in two (a list item
+    # "Related: [[A/B|b]], [[C/D|d]]" became one table row). An escaped pipe is a plain `|` again in the HTML,
+    # which is what WikiLinks expects; code is untouched, it would show the backslash.
+    def self.protect_wiki_link_pipes(text)
+      return text unless text.include?("[[") && text.include?("|")
+
+      text.split(CODE).each_with_index.map do |part, index|
+        index.odd? ? part : part.gsub(WIKI_LINK_PIPE) { |link| link.gsub(/(?<!\\)\|/, "\\\\|") }
+      end.join
     end
+    private_class_method :protect_wiki_link_pipes
 
     # The document without the newlines of the source in its text, for a target that keeps a newline instead of
     # reading it as a space (Confluence): a soft line break becomes a space, the newline after a line break goes.

data/lib/archsight/pdf/cache.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Archsight
+  module Pdf
+    # The last PDFs that were made, by fingerprint of what they were made from, and a limit on how many are made at
+    # the same time (typst needs a CPU for seconds, a page nobody changed needs none).
+    class Cache
+      def initialize(entries: 16, parallel: 2)
+        @entries = entries
+        @store = {}
+        @lock = Mutex.new
+        @slots = SizedQueue.new(parallel)
+        parallel.times { @slots << true }
+      end
+
+      # @param key [String] fingerprint
+      # @yield makes the PDF when it is not cached
+      # @return [String]
+      def fetch(key, &)
+        cached = @lock.synchronize { @store.delete(key)&.tap { |pdf| @store[key] = pdf } }
+        return cached if cached
+
+        pdf = make(&)
+        @lock.synchronize do
+          @store[key] = pdf
+          @store.shift while @store.size > @entries
+        end
+        pdf
+      end
+
+      private
+
+      def make
+        @slots.pop
+        yield
+      ensure
+        @slots << true
+      end
+    end
+  end
+end