Docs Intermediate Reviewed syntax

Multi-Format Documentation

Convert chapter Markdown into TeX, assemble a PDF with `latexmk`, and keep the build directory itself under explicit control. This example is about document pipelines, not marketing-site fluff.

Back to Examples Rules & Targets

Directory Structure

book-project/
chapters/
introduction.md
architecture.md
build/
Netsukefile

This manifest walks chapter files, writes `.tex` output into `build/`, then drives `latexmk` to produce a final `build/book.pdf`.

Why it matters

Directory targets, explicit dependencies, and generated intermediates are part of the language. You do not need a second orchestration layer for document builds.

Annotated Manifest

examples/writing.yml
netsuke_version: "1.0.0"

vars:
  chapters_dir: chapters
  build_dir: build
  pandoc_flags: "-N --pdf-engine=xelatex"
  chapters:
    - introduction
    - architecture

rules:
  - name: tex
    command: "pandoc {{ pandoc_flags }} {{ ins }} -o {{ outs }}"

  - name: combine
    command: >-
      pandoc --standalone {{ ins }} -o {{ build_dir }}/book.tex &&
      latexmk -pdf -outdir={{ build_dir }} {{ build_dir }}/book.tex

  - name: mkdir
    command: "mkdir -p {{ outs }}"

targets:
  - foreach: chapters
    name: "{{ build_dir }}/{{ item }}.tex"
    rule: tex
    sources: "{{ chapters_dir }}/{{ item }}.md"
    deps:
      - "{{ build_dir }}"

  - name: "{{ build_dir }}/book.pdf"
    rule: combine
    sources:
      - "{{ build_dir }}/introduction.tex"
      - "{{ build_dir }}/architecture.tex"

  - name: "{{ build_dir }}"
    rule: mkdir

defaults:
  - build/book.pdf
1

Intermediates are explicit

Each Markdown chapter becomes a TeX file in `build/`. Those files are not hand-waved away; they are graph nodes.

2

Directory creation is modelled too

The build directory has its own target and the chapter outputs depend on it.

3

Ordering is deliberate

The final PDF lists its TeX inputs explicitly, so chapter order stays stable and every dependency is visible in the graph.

Running the Build

Terminal
$ netsuke build build/book.pdf
[1/4] mkdir -p build
[2/4] pandoc -N --pdf-engine=xelatex chapters/introduction.md -o build/introduction.tex
[3/4] pandoc -N --pdf-engine=xelatex chapters/architecture.md -o build/architecture.tex
[4/4] pandoc --standalone build/introduction.tex build/architecture.tex -o build/book.tex && latexmk -pdf -outdir=build build/book.tex

Build Flow

1. Prepare

Create `build/` as a first-class target.

2. Convert

Render each chapter Markdown file to TeX.

3. Order

List the TeX inputs explicitly for stable assembly.

4. Assemble

Run `latexmk` to emit the PDF deliverable.