Convert Typst to YML

Why Convert Typst to YML?

Converting Typst documents to YML format (.yml extension) extracts structured data for use in CI/CD pipelines, Docker configurations, and DevOps automation. The .yml extension is the preferred convention for many tools including GitHub Actions, Docker Compose, Travis CI, and GitLab CI, making it the practical choice for integration with development workflows.

The .yml extension is functionally identical to .yaml -- both use the same YAML specification. However, many CI/CD tools and development platforms specifically expect .yml files. GitHub Actions uses .github/workflows/*.yml, Docker Compose uses docker-compose.yml, and Travis CI uses .travis.yml. Converting to .yml ensures compatibility with these tool conventions.

For technical teams that document their infrastructure and DevOps practices in Typst, converting to YML bridges the gap between documentation and configuration. Architecture decisions, service configurations, and deployment procedures written in Typst can be extracted as structured YML data that feeds into automation pipelines.

Typst's scripting capabilities allow authors to define structured data using #let bindings with arrays and dictionaries. When converting to YML, these data structures map directly to YAML sequences and mappings, preserving the semantic structure of the original Typst document in a format ready for DevOps tooling.

Key Benefits of Converting Typst to YML:

• CI/CD Ready: Output uses the .yml extension expected by GitHub Actions, Travis CI
• Docker Compatible: Generate docker-compose.yml compatible data
• DevOps Standard: .yml is the convention in DevOps tooling
• Human Readable: Clean indentation-based syntax
• Comments Support: Add annotations to extracted data
• Automation: Feed into CI/CD pipelines and infrastructure automation
• JSON Compatible: YML (YAML) is a superset of JSON

Practical Examples

Example 1: Project Documentation to Config

Input Typst file (project.typ):

#set document(
  title: "Microservice Architecture",
  author: "Engineering Team",
)

= Microservice Architecture

== Services
Our platform consists of the following
*core services*:

- _auth-service_: User authentication
- _api-gateway_: Request routing
- _data-service_: Database operations

Output YML file (project.yml):

# Microservice Architecture
# Converted from Typst document
title: Microservice Architecture
author: Engineering Team

services:
  - name: auth-service
    description: User authentication
  - name: api-gateway
    description: Request routing
  - name: data-service
    description: Database operations

Example 2: Research Paper Metadata

Input Typst file (paper.typ):

#set document(
  title: "Federated Learning at Scale",
  author: ("Sarah Kim", "James Liu"),
  date: datetime(year: 2026, month: 2, day: 15),
)

= Federated Learning at Scale

== Abstract
We present a scalable framework for
federated learning across heterogeneous
edge devices with differential privacy.

Output YML file (paper.yml):

# Paper metadata
title: Federated Learning at Scale
authors:
  - Sarah Kim
  - James Liu
date: 2026-02-15

abstract: |
  We present a scalable framework for
  federated learning across heterogeneous
  edge devices with differential privacy.

Example 3: Table Data Extraction

Input Typst file (infra.typ):

= Infrastructure Inventory

#let servers = (
  (host: "web-01", cpu: 4, ram: 16, region: "us-east"),
  (host: "web-02", cpu: 4, ram: 16, region: "eu-west"),
  (host: "db-01", cpu: 8, ram: 64, region: "us-east"),
)

#table(
  columns: 4,
  [*Host*], [*CPU*], [*RAM (GB)*], [*Region*],
  ..servers.map(s =>
    (s.host, str(s.cpu), str(s.ram), s.region)
  ).flatten()
)

Output YML file (infra.yml):

# Infrastructure Inventory
servers:
  - host: web-01
    cpu: 4
    ram: 16
    region: us-east
  - host: web-02
    cpu: 4
    ram: 16
    region: eu-west
  - host: db-01
    cpu: 8
    ram: 64
    region: us-east

Frequently Asked Questions (FAQ)

Q: What is the difference between .yml and .yaml?

A: There is no functional difference. Both extensions use the same YAML specification and are parsed identically. The .yml extension is shorter and preferred by many CI/CD tools (GitHub Actions, Docker Compose, Travis CI), while .yaml is the official extension recommended by the YAML specification. Choose based on your tool's convention.

Q: Why choose YML output over YAML?

A: Choose .yml when the target tool or workflow specifically expects that extension. GitHub Actions workflows must be .yml files, Docker Compose uses docker-compose.yml by default, and many CI/CD platforms use .yml convention. The content is identical; only the file extension differs.

Q: Can I use the output in GitHub Actions?

A: The converted YML contains structured data from the Typst document. While it is not a GitHub Actions workflow definition, the extracted metadata and configuration data can be used within GitHub Actions workflows for automated publishing, documentation generation, or data processing pipelines.

Q: How does Typst scripting map to YML?

A: Typst's #let bindings with arrays map to YAML sequences, and dictionaries map to YAML mappings. Computed values from expressions are resolved to their final values. The YML output represents the document's data structure, not the scripting logic.

Q: Are mathematical equations preserved?

A: Equations from $ ... $ blocks are stored as string values in the YML output. YAML's multi-line string support handles complex equations. The notation is retained for rendering by MathJax or KaTeX in downstream applications.

Q: How do I validate the YML output?

A: Use yamllint for syntax checking, or the YAML validation extensions in VS Code and IntelliJ. For CI/CD-specific validation, tools like actionlint (for GitHub Actions) or docker-compose config can verify the structure meets specific tool requirements.

Q: Can Typst read YML files?

A: Yes. Typst's built-in yaml() function reads both .yml and .yaml files natively. This enables round-trip workflows where document metadata is extracted to YML, potentially modified, and then read back into Typst templates for generating formatted documents from structured data.

Q: Is there a size limit for YML output?

A: There is no inherent size limit in the YAML specification. However, YML is best suited for configuration and metadata, not large document content. For very large Typst documents, the YML output focuses on metadata and structural information rather than full text content, keeping the file manageable.