0
# Foliant
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: foliant
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install foliant`
10
- **Requirements**: Python ^3.6
11
- **Dependencies**: pyyaml, cliar, prompt_toolkit
12
13
## Core Imports
14
15
```python
16
import foliant
17
```
18
19
For direct API access:
20
21
```python
22
from foliant.cli import entry_point
23
from foliant.config import Parser
24
from foliant.utils import get_available_backends, get_available_tags
25
from foliant.backends.base import BaseBackend
26
from foliant.preprocessors.base import BasePreprocessor
27
```
28
29
## Basic Usage
30
31
### Command Line Usage
32
33
```bash
34
# Install foliant
35
pip install foliant
36
37
# Basic build command
38
foliant make html
39
40
# Build with specific backend
41
foliant make pdf --with pandoc
42
43
# Build with custom project path
44
foliant make html --path /path/to/project
45
46
# Quiet mode for scripting
47
foliant make html --quiet
48
49
# Debug mode
50
foliant make html --debug
51
```
52
53
### Programmatic Usage
54
55
```python
56
from foliant.cli.make import Cli
57
from pathlib import Path
58
59
# Create CLI instance
60
cli = Cli()
61
62
# Build documentation programmatically
63
result = cli.make(
64
target='html',
65
backend='mkdocs',
66
project_path=Path('./my-docs'),
67
config_file_name='foliant.yml',
68
quiet=False,
69
debug=False
70
)
71
72
print(f"Generated documentation at: {result}")
73
```
74
75
## Architecture
76
77
Foliant follows a modular, plugin-based architecture:
78
79
- **CLI Layer**: Command-line interface built on `cliar`, extensible via CLI plugins
80
- **Config Layer**: YAML configuration parsing with support for custom tags (`!include`, `!path`, `!env`)
81
- **Backend Layer**: Output generation backends (Pandoc, MkDocs, etc.) that transform content
82
- **Preprocessor Layer**: Content transformation plugins that modify Markdown before backend processing
83
- **Utilities Layer**: Common functions for plugin discovery and system integration
84
85
This design enables maximum flexibility and extensibility, allowing users to create custom plugins or integrate with existing documentation workflows.
86
87
## Capabilities
88
89
### Command Line Interface
90
91
Primary interface for building documentation with configurable targets, backends, and options. Supports interactive backend selection and comprehensive logging.
92
93
```python { .api }
94
def entry_point(): ...
95
96
class Cli(BaseCli):
97
def make(self, target, backend='', project_path=Path('.'),
98
config_file_name='foliant.yml', logs_dir='',
99
quiet=False, keep_tmp=False, debug=False): ...
100
```
101
102
[CLI System](./cli.md)
103
104
### Configuration System
105
106
YAML-based configuration with extensible tag system for includes, path resolution, and environment variables. Supports modular parser architecture for custom configuration features.
107
108
```python { .api }
109
class Parser:
110
def parse(self) -> dict: ...
111
112
class BaseParser:
113
def __init__(self, project_path: Path, config_file_name: str,
114
logger: Logger, quiet: bool = False): ...
115
def parse(self) -> dict: ...
116
```
117
118
[Configuration](./config.md)
119
120
### Backend System
121
122
Pluggable output generation system supporting multiple document formats. Backends orchestrate preprocessors and handle final document generation.
123
124
```python { .api }
125
class BaseBackend:
126
targets: tuple
127
def __init__(self, context: dict, logger: Logger,
128
quiet=False, debug=False): ...
129
def preprocess_and_make(self, target: str) -> str: ...
130
def make(self, target: str) -> str: ...
131
```
132
133
[Backends](./backends.md)
134
135
### Preprocessor System
136
137
Content transformation system for modifying Markdown before backend processing. Supports tag-based content processing and modular preprocessor architecture.
138
139
```python { .api }
140
class BasePreprocessor:
141
defaults: dict
142
tags: tuple
143
def __init__(self, context: dict, logger: Logger,
144
quiet=False, debug=False, options={}): ...
145
def apply(self): ...
146
```
147
148
[Preprocessors](./preprocessors.md)
149
150
### Utility Functions
151
152
Helper functions for plugin discovery, package management, and common operations across the Foliant ecosystem.
153
154
```python { .api }
155
def get_available_backends() -> Dict[str, Tuple[str]]: ...
156
def get_available_tags() -> Set[str]: ...
157
def get_available_clis() -> Dict[str, Type]: ...
158
def get_foliant_packages() -> List[str]: ...
159
```
160
161
[Utilities](./utils.md)
162
163
## Types
164
165
```python { .api }
166
OptionValue = int | float | bool | str
167
168
# Context dictionary structure
169
Context = {
170
'project_path': Path,
171
'config': dict,
172
'target': str,
173
'backend': str
174
}
175
176
# Configuration defaults
177
ConfigDefaults = {
178
'src_dir': Path('./src'),
179
'tmp_dir': Path('./__folianttmp__')
180
}
181
```