One of the primary differences between the distros (variations) of your documentation sets is that some may include topics or even whole groups of topics that others don’t. For example, if your documentation set was all about an airplane, you might want to write everything about flying and repairing the airplane in a single repo. But when you publish your docs, you might want to publish the repair-related topics as one distro and the flying-related topics as another.
AsciiBinder supports this by enabling you to "distro tag" topics and topic groups within your topic map file through the use of the Distros:
setting. The distro tags that you use for this purpose are defined in your distro map file.
As an example, continuing the airplane documentation analogy, assume your _distro_map.yml
file looks like this:
Airplane Docs _distro_map.yml
file extract
---
piloting-guide: (1)
name: Flymaster 9000 Piloting Guide
...
---
repair-guide: (2)
name: Flymaster 9000 Repair Guide
...
1 |
The piloting-guide distro key, which we’ll use to denote flying-related content |
2 |
The repair-guide distro key, which we’ll use to denote repair-related content |
Then your topic map file may look like this:
Airplane Docs _topic_map.yml
file
---
Name: The Flymaster 9000
Dir: welcome
Topics:
- Name: Welcome
File: index
- Name: What is an Airplane?
File: what_is_an_airplane
---
Name: Airplane Concepts
Dir: airplane_concepts
Topics:
- Name: Passenger Compartment
File: passenger_compartment
- Name: Engine Compartment
File: engine_compartment
Distros: repair-guide (1)
- Name: Cockpit
File: cockpit
---
Name: Air Navigation
Dir: air_navigation
Distros: piloting-guide (2)
Topics:
- Name: Calculating Ground Speed
File: ground_speed
- Name: Using a Compass
File: compass_usage
1 |
This topic-level distro tag ensures that the "Engine Compartment" topic will only appear in the "Repair Guide" distro. |
2 |
This topic-group-level distro tag ensures that the "Air Navigation" topic group will only appear in the "Piloting Guide distro. |
When a topic or a topic group excludes the Distros:
setting, this is the same as saying Distros: all
. The "all" value is a reserved keyword meaning "valid for every defined distro".
The Distros:
setting also supports a comma delimited list of values:
Distros: distro-key-1,distro-key-2
AsciiBinder also supports the use of wildcards in distro keys inside of the topic map file. For instance, per our airplane example, this entry would be automatically expanded to piloting-guide,repair-guide
:
Distro keys can also be used to conditionalize content inside of individual topic files; this is discussed in detail in the Writer’s Guide.