The folder contains external repositories that contributes additional pages.
All repositories are included into external
folder in the project root.
The path MUST be listed in the .gitignore
to avoid side effects with git repositories mixtures
The following code is used to enable an external in data/_nav.yml
:
- title: Native
external:
path: kotlin-native
nav: _nav_reference.yml
base: /docs/reference/native
branch: master
repo: https://github.com/JetBrains/kotlin-native
where:
path
is the checkout path under theexternal
foldernav
means the file, relative to thepath
with the YAML spec (see blow)base
selects base URL for all resources that are included from thenav
NOTE the base path is REMOVED and re-created on every reload!branch
branch in the repository for edit on GitHub linksrepo
is a string, that is used in warning and informational messageswrap_code_snippets
to automatically wrap```
blocks into our special<div>
(only for Kotlin right now)inline
to make all pages included replacing the current element
The docker-compose up
command allows running without externals
checked out.
That is done so to simplify the process for everyone who is working on the
kotlin-web-site
repo. We ensure that all listed externals are available when
building the static site ( build_mode == True
)
The nav
format is a list of:
- md: IMMUTABILITY.md
url: immutability.html
title: "Immutability"
where:
md
is the name of the original markdown file to includeurl
is the URL at the resulting sitetitle
is the title
Optionally for every item replacements are supported:
replace:
- regex: '\[data class\]\(data-classes\)'
with: '[data class](\#data-classes)'
The code uses regular expression for Python re package to replace text entries with .sub
function.
Those parameters are translated into the content
element under the original _nav.yml
file. Thanks to the separated md
and url
fields one is able to setup alias names for resources.
The flask
site lists filesystem to collect all .md
files to generate pages for.
The approach is hard to upgrade, and it blocks us from placing externals directly
under pages
folder. That is why we symlink files at the generation time.
The approach allows fixing URL names for free. The symlink is used to support edit
and reload pattern