or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

backends.mdcli.mdconfig.mdindex.mdpreprocessors.mdutils.md
tile.json

tessl/pypi-foliant

Modular, Markdown-based documentation generator that makes pdf, docx, html, and more.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/foliant@1.0.x

To install, run

npx @tessl/cli install tessl/pypi-foliant@1.0.0

index.mddocs/

Foliant

Foliant is an all-in-one modular documentation authoring tool that enables developers and technical writers to produce multiple output formats (PDF, DOCX, static websites, Confluence pages) from single Markdown source files. It serves as a higher-order tool that orchestrates other programs like Pandoc, MkDocs, Aglio, and Slate to generate documentation in various formats.

Package Information

  • Package Name: foliant
  • Package Type: pypi
  • Language: Python
  • Installation: pip install foliant
  • Requirements: Python ^3.6
  • Dependencies: pyyaml, cliar, prompt_toolkit

Core Imports

import foliant

For direct API access:

from foliant.cli import entry_point
from foliant.config import Parser
from foliant.utils import get_available_backends, get_available_tags
from foliant.backends.base import BaseBackend
from foliant.preprocessors.base import BasePreprocessor

Basic Usage

Command Line Usage

# Install foliant
pip install foliant

# Basic build command
foliant make html

# Build with specific backend
foliant make pdf --with pandoc

# Build with custom project path
foliant make html --path /path/to/project

# Quiet mode for scripting
foliant make html --quiet

# Debug mode
foliant make html --debug

Programmatic Usage

from foliant.cli.make import Cli
from pathlib import Path

# Create CLI instance
cli = Cli()

# Build documentation programmatically
result = cli.make(
    target='html',
    backend='mkdocs',
    project_path=Path('./my-docs'),
    config_file_name='foliant.yml',
    quiet=False,
    debug=False
)

print(f"Generated documentation at: {result}")

Architecture

Foliant follows a modular, plugin-based architecture:

  • CLI Layer: Command-line interface built on cliar, extensible via CLI plugins
  • Config Layer: YAML configuration parsing with support for custom tags (!include, !path, !env)
  • Backend Layer: Output generation backends (Pandoc, MkDocs, etc.) that transform content
  • Preprocessor Layer: Content transformation plugins that modify Markdown before backend processing
  • Utilities Layer: Common functions for plugin discovery and system integration

This design enables maximum flexibility and extensibility, allowing users to create custom plugins or integrate with existing documentation workflows.

Capabilities

Command Line Interface

Primary interface for building documentation with configurable targets, backends, and options. Supports interactive backend selection and comprehensive logging.

def entry_point(): ...

class Cli(BaseCli):
    def make(self, target, backend='', project_path=Path('.'), 
             config_file_name='foliant.yml', logs_dir='', 
             quiet=False, keep_tmp=False, debug=False): ...

CLI System

Configuration System

YAML-based configuration with extensible tag system for includes, path resolution, and environment variables. Supports modular parser architecture for custom configuration features.

class Parser:
    def parse(self) -> dict: ...

class BaseParser:
    def __init__(self, project_path: Path, config_file_name: str, 
                 logger: Logger, quiet: bool = False): ...
    def parse(self) -> dict: ...

Configuration

Backend System

Pluggable output generation system supporting multiple document formats. Backends orchestrate preprocessors and handle final document generation.

class BaseBackend:
    targets: tuple
    def __init__(self, context: dict, logger: Logger, 
                 quiet=False, debug=False): ...
    def preprocess_and_make(self, target: str) -> str: ...
    def make(self, target: str) -> str: ...

Backends

Preprocessor System

Content transformation system for modifying Markdown before backend processing. Supports tag-based content processing and modular preprocessor architecture.

class BasePreprocessor:
    defaults: dict
    tags: tuple
    def __init__(self, context: dict, logger: Logger, 
                 quiet=False, debug=False, options={}): ...
    def apply(self): ...

Preprocessors

Utility Functions

Helper functions for plugin discovery, package management, and common operations across the Foliant ecosystem.

def get_available_backends() -> Dict[str, Tuple[str]]: ...
def get_available_tags() -> Set[str]: ...
def get_available_clis() -> Dict[str, Type]: ...
def get_foliant_packages() -> List[str]: ...

Utilities

Types

OptionValue = int | float | bool | str

# Context dictionary structure
Context = {
    'project_path': Path,
    'config': dict,
    'target': str,
    'backend': str
}

# Configuration defaults
ConfigDefaults = {
    'src_dir': Path('./src'),
    'tmp_dir': Path('./__folianttmp__')
}