Contributing to DocumenterTypst.jl

Thank you for your interest in contributing to DocumenterTypst.jl!

Code of Conduct

This project follows the Julia Community Standards.

Getting Started

Setting Up Your Development Environment

Fork and clone the repository:

git clone https://github.com/lucifer1004/DocumenterTypst.jl
cd DocumenterTypst.jl

Install dependencies:

using Pkg
Pkg.activate(".")
Pkg.instantiate()

Run tests:
```
Pkg.test()
```

Making Changes

Workflow

Create a new branch for your changes:
```
git checkout -b your-feature-branch
```
Make your changes and commit them with clear messages:
```
git commit -m "Add feature X"
```
Push to your fork and create a pull request:
```
git push origin your-feature-branch
```

Code Style

We use:

Runic.jl for Julia code formatting
markdownlint-cli2 for Markdown linting

Format your code before committing:

using Pkg
Pkg.add("Runic")
using Runic
Runic.main(["--verbose", "."])

Or use the justfile (formats both Julia and Markdown):

just format

This command will:

Format Julia code with Runic
Lint and auto-fix Markdown files with markdownlint-cli2

CI will check formatting automatically using Runic v1.2 and markdownlint-cli2.

Testing

Running Tests

using Pkg
Pkg.test("DocumenterTypst")

Or with just:

just test

Typst Backend Tests

Test the Typst backend with different platforms:

# Using just (recommended)
just test-backend           # Typst_jll (default)
just test-backend native    # System typst
just test-backend none      # Only .typ generation (fastest)

# Manual run
TYPST_PLATFORM=typst julia --project=test/integration test/integration/runtests.jl

Available platforms:

typst (default): Uses Typst_jll.jl, automatic cross-platform
native: Uses system-installed typst command
none: Only generates .typ files, no PDF compilation (fastest, recommended for development)

Adding Tests

When adding new features:

Add unit tests to test/runtests.jl
Test both success and error cases
Ensure tests are fast (use platform="none" to skip compilation)

Example:

@testset "New Feature" begin
    output = render_to_typst("**new syntax**")
    @test contains(output, "expected output")
end

Test Coverage

We aim for 90%+ code coverage. Check coverage locally:

using Pkg
Pkg.test("DocumenterTypst"; coverage=true)

Documentation

Building Documentation Locally

# HTML documentation
just docs

# Or manually
julia --project=docs -e '
  using Pkg
  Pkg.develop(PackageSpec(path=pwd()))
  Pkg.instantiate()
  include("docs/make.jl")
'

# Typst/PDF documentation with different platforms
just docs-typst           # Use Typst_jll (default)
just docs-typst native    # Use system typst
just docs-typst none      # Generate .typ source only (fastest for preview)

HTML output will be in docs/build/, Typst/PDF output in docs/build-typst/.

Documentation Style

Use clear, concise language
Provide code examples
Include "See also" links
Test all code examples

Changelog

All user-visible changes must have a changelog entry.

Adding a Changelog Entry

Edit CHANGELOG.md under the "Unreleased" section:

## Unreleased

### Added

- New feature description. ([#123])

### Fixed

- Bug fix description. ([#124])

Linking Issues/PRs

Reference issues and PRs using ([#123]) notation. The link will be auto-generated.

Skip Changelog

For trivial changes (typo fixes, CI tweaks), add the Skip Changelog label to your PR.

Pull Request Guidelines

Before Submitting

[ ] Code is formatted (just format or Runic.jl)
[ ] Tests pass locally (Pkg.test())
[ ] Typst backend tests pass (if applicable)
[ ] Spell check passes (typos)
[ ] Changelog updated (if needed)
[ ] Documentation updated (if adding features)
[ ] Commit messages are clear

CI Checks

Your PR will be automatically checked for:

✅ Julia code formatting (Runic)
✅ Spell checking (Typos)
✅ File formatting (Prettier)
✅ Changelog update
✅ Tests on Linux/macOS/Windows
✅ Typst backend tests
✅ Documentation build
✅ Link checking
✅ Code coverage

All checks must pass before merging.

PR Description

Include:

What: What does this PR do?
Why: Why is this change needed?
How: How does it work?
Testing: How was it tested?

Example:

## What

Adds support for custom fonts in Typst output.

## Why

Users want to match their organization's branding.

## How

- Adds `fonts` parameter to `Typst` constructor
- Passes `--font-path` to Typst compiler
- Updates documentation and tests

## Testing

- Added unit tests for font path generation
- Tested with custom font on Linux/macOS/Windows
- Updated docs with example

Closes #42

Review Process

Automated CI checks must pass
At least one maintainer approval required
No unresolved review comments
Up-to-date with main branch

Issue Guidelines

Before Opening an Issue

Search existing issues - Your issue may already exist
Check documentation - The answer might be there
Try latest version - The bug might be fixed

Bug Reports

Include:

Summary: Brief description
Steps to reproduce: Minimal reproducible example
Expected behavior: What should happen
Actual behavior: What actually happens

Environment:

Julia version:
DocumenterTypst version:
OS:

Minimal example: Complete code to reproduce

Feature Requests

Include:

Use case: Why is this needed?
Proposed solution: How should it work?
Alternatives considered: Other approaches?
Examples: Code examples of desired API

Development Tips

Quick Iteration

For fast development cycles, generate only .typ source without compilation:

# Using just
just docs-typst none

# Or manually
julia --project=docs docs/make.jl typst none

Then compile manually when needed:

cd docs/build-typst
typst compile YourPackage.typ

Debugging

Enable debug output:

export DOCUMENTER_TYPST_DEBUG="debug-output"
export DOCUMENTER_VERBOSE="true"
julia docs/make.jl

Check generated files in debug-output/.

Testing Against Documenter Main

Test compatibility with Documenter development version:

using Pkg
Pkg.add(name="Documenter", rev="main")
Pkg.test("DocumenterTypst")

Release Process

(For maintainers)

Update CHANGELOG.md:
- Move "Unreleased" to "Version [vX.Y.Z] - YYYY-MM-DD"
- Add version comparison link
- Create new "Unreleased" section
Update Project.toml version

Commit and tag:

git commit -am "Release vX.Y.Z"
git tag vX.Y.Z
git push origin main --tags

Register with JuliaRegistrator:
```
@JuliaRegistrator register
```
GitHub Actions will automatically:
- Run full test suite
- Build documentation
- Create GitHub release

Getting Help

Questions: Open a Discussion
Bugs: Open an Issue
Chat: Join Julia Slack #documentation channel

Recognition

Contributors will be:

Listed in release notes
Acknowledged in documentation
Added to .zenodo.json (if substantial contribution)

Thank you for contributing! 🎉