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
```