Add docs for pandoc/typst

pandoc · Oct 22, 2024 · e376c2b · e376c2b
1 parent 6bed800
commit e376c2b
Show file tree

Hide file tree

Showing 9 changed files with 98 additions and 69 deletions.
diff --git a/Makefile b/Makefile
@@ -205,7 +205,13 @@ test-typst:
 lint:
 	shellcheck $(shell find . -name "*.sh")
 
-.PHONY: docs docs-minimal
+.PHONY: docs \
+		docs-minimal \
+		docs-core \
+		docs-latex \
+		docs-extra \
+		docs-typst \
+
 docs:
 	@pandoc "docs/$(REPO).md" \
 		--lua-filter="docs/filters/transclude.lua" \
@@ -226,6 +232,9 @@ docs-latex: docs
 docs-extra: REPO = extra
 docs-extra: docs
 
+docs-typst: REPO = typst
+docs-typst: docs
+
 .PHONY: clean
 clean:
 	IMAGE=none make -C test clean
diff --git a/docs/core.md b/docs/core.md
@@ -20,7 +20,7 @@ docs/sections/quick-reference.md
 docs/sections/supported-tags.md
 ```
 
-Supported stacks <a name="supported-stacks"></a>
+Supported stacks
 ------------------------------------------------------------------
 
 All tags can be suffixed with a stack-identifier, e.g.,
@@ -37,18 +37,5 @@ The default for `pandoc/core` is `alpine`.
 
 ``` include
 docs/sections/run.md
+docs/sections/other-images.md
 ```
-
-Other images
------------------------------------------------------------------
-
-If the images here do not fit your use-case, then checkout these
-alternatives:
-
--   [**pandoc/minimal**][]: small images with the pandoc executable.
--   [**pandoc/latex**][]: suitable for conversions to PDF via [LaTeX].
-
-[LaTeX]: https://latex-project.org/
-
-[**pandoc/minimal**]: https://hub.docker.com/r/pandoc/minimal
-[**pandoc/latex**]: https://hub.docker.com/r/pandoc/latex
diff --git a/docs/extra.md b/docs/extra.md
@@ -28,7 +28,7 @@ docs/sections/quick-reference.md
 docs/sections/supported-tags.md
 ```
 
-Supported stacks <a name="supported-stacks"></a>
+Supported stacks
 ------------------------------------------------------------------
 
 All tags can be suffixed with a stack-identifier, e.g.,
@@ -46,20 +46,5 @@ The default for `pandoc/extra` is `alpine`.
 
 ``` include
 docs/sections/run.md
+docs/sections/other-images.md
 ```
-
-Other images
-------------------------------------------------------------------
-
-If the images here do not fit your use-case, then checkout these
-alternatives:
-
--   [**pandoc/minimal**][]: small images with the pandoc executable.
--   [**pandoc/core**][]: based on minimal images, but ships with
-    additional programs commonly used during conversions.
--   [**pandoc/latex**][]: based on core images, but ships with a basic
-    [LaTeX] installation.
-
-[**pandoc/minimal**]: https://hub.docker.com/r/pandoc/minimal
-[**pandoc/core**]: https://hub.docker.com/r/pandoc/core
-[**pandoc/latex**]: https://hub.docker.com/r/pandoc/latex
diff --git a/docs/filters/transclude.lua b/docs/filters/transclude.lua
@@ -4,8 +4,14 @@ function CodeBlock (cb)
     return nil
   end
 
-  -- open file
-  local fh = io.open(cb.text:match '[^\n]+')
-
-  return pandoc.read(fh:read 'a', FORMAT, PANDOC_READER_OPTIONS).blocks
+  local blocks = pandoc.Blocks{}
+  for filename in cb.text:gmatch '[^\n]+' do
+    -- open file
+    local fh = io.open(filename)
+    blocks:extend(
+      pandoc.read(fh:read 'a', 'markdown', PANDOC_READER_OPTIONS).blocks
+    )
+    fh:close()
+  end
+  return blocks
 end
diff --git a/docs/latex.md b/docs/latex.md
@@ -21,7 +21,7 @@ docs/sections/quick-reference.md
 docs/sections/supported-tags.md
 ```
 
-Supported stacks <a name="supported-stacks"></a>
+Supported stacks
 ------------------------------------------------------------------
 
 All tags can be suffixed with a stack-identifier, e.g.,
@@ -55,15 +55,6 @@ derivative images may experience problems if the TeXLive version
 has been newly frozen. This can be resolved by pulling the
 updated base image again.
 
-Other images
-------------------------------------------------------------------
-
-If the images here do not fit your use-case, then checkout these
-alternatives:
-
--   [**pandoc/minimal**][]: small images with the pandoc executable.
--   [**pandoc/core**][]: based on minimal images, but ships with
-    additional programs commonly used during conversions.
-
-[**pandoc/minimal**]: https://hub.docker.com/r/pandoc/minimal
-[**pandoc/core**]: https://hub.docker.com/r/pandoc/core
+``` include
+docs/sections/other-images.md
+```
diff --git a/docs/minimal.md b/docs/minimal.md
@@ -17,7 +17,7 @@ docs/sections/quick-reference.md
 docs/sections/supported-tags.md
 ```
 
-Supported stacks <a name="supported-stacks"></a>
+Supported stacks
 ------------------------------------------------------------------
 
 All tags can be suffixed with a stack-identifier, e.g.,
@@ -36,19 +36,5 @@ The default for `pandoc/minimal` is `static`.
 
 ``` include
 docs/sections/run.md
+docs/sections/other-images.md
 ```
-
-Other images
------------------------------------------------------------------
-
-If the images here do not fit your use-case, then checkout these
-alternatives:
-
--   [**pandoc/core**][]: based on minimal images, but ships with
-    additional programs commonly used during conversions.
--   [**pandoc/latex**][]: suitable for conversions to PDF via [LaTeX].
-
-[LaTeX]: https://latex-project.org/
-
-[**pandoc/core**]: https://hub.docker.com/r/pandoc/core
-[**pandoc/latex**]: https://hub.docker.com/r/pandoc/latex
diff --git a/docs/sections/other-images.md b/docs/sections/other-images.md
@@ -0,0 +1,22 @@
+Other images
+------------------------------------------------------------------
+
+The following pandoc images are available:
+
+-   [**pandoc/minimal**][]: small images with the pandoc executable.
+-   [**pandoc/core**][]: based on minimal images and includes
+    additional programs that are commonly used during conversions.
+-   [**pandoc/latex**][]: suitable for conversions to PDF via [LaTeX].
+-   [**pandoc/extra**][]: large images based on the pandoc/latex,
+    with more helpers, the Tectonic engine, and the [Eisvogel
+    template][]
+-   [**pandoc/typst**][]: includes the [Typst][typst-app]
+    typesetting system.
+
+[**pandoc/minimal**]: https://hub.docker.com/r/pandoc/minimal
+[**pandoc/core**]: https://hub.docker.com/r/pandoc/core
+[**pandoc/extra**]: https://hub.docker.com/r/pandoc/extra
+[**pandoc/typst**]: https://hub.docker.com/r/pandoc/typst
+[Eisvogel template]: https://github.com/Wandmalfarbe/pandoc-latex-template
+[LaTeX]: https://latex-project.org/
+[typst-app]: https://typst.app/
diff --git a/docs/sections/supported-tags.md b/docs/sections/supported-tags.md
@@ -15,10 +15,9 @@ The *latest* tag refers to the most recently released version;
 there may be a minor lag between the time a pandoc version is
 released and a new image is released.
 
-A recent development version is provided under the *edge* tag. 
+A recent development version is provided under the *edge* tag.
 
-All tags can be suffixed with a stack identifier (see [Supported
-stacks](#supported-stacks)).
+All tags can be suffixed with a stack identifier.
 
 ### A note on pandoc versioning
 

diff --git a/docs/typst.md b/docs/typst.md
@@ -0,0 +1,44 @@
+Pandoc Typst images
+==================================================================
+
+These images contain [pandoc][], the universal document converter,
+and [Typst][], a fast and modern typesetting system that can be
+used to produce PDFs.
+
+[pandoc]: https://pandoc.org/
+[Typst]: https://typst.app
+
+``` include
+docs/sections/quick-reference.md
+```
+
+``` include
+docs/sections/supported-tags.md
+```
+
+Supported stacks
+------------------------------------------------------------------
+
+All tags can be suffixed with a stack-identifier, e.g.,
+`latest-ubuntu`. This allows to chose a specific operation system.
+Available stacks are
+
+- *alpine*: [Alpine] Linux.
+- *ubuntu*: [Ubuntu] Linux.
+
+The default for `pandoc/typst` is `alpine`.
+
+[Alpine]: https://alpinelinux.org/
+[Ubuntu]: https://ubuntu.org/
+
+
+``` include
+docs/sections/run.md
+```
+
+Use the `--pdf-engine=typst` pandoc option to generate a PDF via
+Typst.
+
+``` include
+docs/sections/other-images.md
+```