-
Notifications
You must be signed in to change notification settings - Fork 332
/
schema.yaml
143 lines (117 loc) · 4.72 KB
/
schema.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
# Schema for conf.yaml, used by yamale.
include("conf")
---
conf:
# Mapping of repo "slugs" to their URLs. All repos are fetched at the
# beginning of a build.
repos: map(str(), str())
variables: map()
# Used as the top-level title for the Table of Contents, and therefore the
# entire site.
contents_title: str()
toc_extra: str()
contents: list(include("section"))
redirects: list(include("redirect"))
---
# Top-level section of the guide
section:
title: str()
sections: list(any(include("book"), include("subsection")))
---
subsection:
# `title` and `sections` are the same as above.
title: str()
sections: list(any(include("book"), include("subsection")))
# Sections other than the top-level sections have some additional options
# that apply to books within that sub-section.
# URL prefix added to all book URLs within this subsection.
base_dir: str(required=False)
# Just for custom-language sections. TODO: Is this redundant with the `lang`
# defined in each book?
lang: str(required=False)
# toc_extra is supported on both individual books, and sub-TOCs (subpages
# with their own lists of books).
toc_extra: str(required=False)
---
book:
# Title of the book (used in headers, and in lists of books)
title: str()
# URL prefix of this book (under https://www.elastic.co/guide/<prefix>),
# unless this book is part of a subsection which has its own base_dir. Then,
# the URL is https://www.elastic.co/guide/<base_dir>/<prefix>)
prefix: str()
# List of all versions of the book being published. If only one branch is
# listed, there won't be a "other versions" link, or a version dropdown in
# the table of contents.
# This list should be in order from "newest" to "oldest". A branch's
# position in this list relative to the "current" branch will be used to
# determine if a non-current branch is shown as "newer" or "older" than the
# "current" branch.
# TODO: Change this to "versions".
branches: list(include("branch_spec"))
# The default version of the book that appears.
# TODO: Change this to a "version".
current: include("branch")
# List of branches shown by default in the dropdown (and are still receiving updates)
# All items in this list must also be in `branches`.
# TODO: Change this to be a list of versions.
live: list(include("branch"), required=False)
subject: str()
tags: str()
sources: list(include("source"))
index: str()
chunk: int(required=False)
noindex: int(required=False)
private: int(required=False)
single: int(required=False)
toc: int(required=False)
toc_extra: str(required=False)
repo: str(required=False) # TODO: Remove?
respect_edit_url_overrides: bool(required=False)
lang: str(required=False)
suppress_migration_warnings: bool(required=False)
---
# A branch of a git repository used to build a book. In many places, the branch
# is used as a synonym for a version. Since branch names are often `x.y` (which
# is a number in YAML), `str()` isn't sufficient.
# TODO: Use "version" in most places to refer to editions of a book, and
# restrict "branch" to just being used for git operations.
branch: any(str(), num())
# A version of a book.
version: any(str(), num())
# An item that can go in the `branches` list. Each item in the list can be a
# single branch, or a branch_version_map. For example:
# - master
# - 7.9
# - 7.x
# - { branch-1.0: v1.0 }
branch_spec: any(include("branch"), include("version_map"))
# A map with a single key, mapping a branch name to a version name.
# TODO: Swap the order of this mapping, so we can use `versions` as the primary
# key, and map the version to a branch name when they aren't the same.
version_map: map(include("version"), key=include("branch"))
---
# A source is a collection of files used when building a book.
source:
# The "slug" for a repo, must be a key in `repos`.
repo: str()
# Path within the repo for all files used for the build. This is passed to
# `git-archive`, so only these files are available. This path is also used
# to detect changes, and causes a rebuild when any files on this path
# change.
path: str()
# List of branches which don't depend on this source
exclude_branches: list(include("branch"), required=False)
prefix: str(required=False)
private: bool(required=False)
alternatives: include("alternative", required=False)
# TODO: Are these actually branches or versions? They're equivalent in this schema.
map_branches: map(include("branch"), key=include("branch"), required=False)
---
alternative:
source_lang: str()
alternative_lang: str()
---
redirect:
prefix: str()
redirect: str()