Static sites for arXiv.

To build the arXiv docs site, run:

python -m venv docs-venv
docs-venv/bin/activate
pip install -r requirements.txt
mkdocs serve

Then you will have the site served locally with hot reloading on edits. In your browser, go to http://localhost:8000/index.html

Each site should be contained in a single directory. For example:

mysite/
├── index.md
├── specifics/
|   ├── impressive.png
|   └── coolstory.md
└── _templates
    └── mysite
        └── custom.html

The directory structure in the site directory determines the site map. A file at foo/baz/bat.md will be served at https://some.site/foo/baz/bat.html and the file foo/baz/index.md will be served at https://some.site/foo/baz/index.html.

Both absolute and relative links work. You can add a link in foo/index.md to foo/baz.md with either [click this absolute link](/foo/baz.md) or [click this relative link](baz.md). Relative links assist in movig directories of pages around since a whole subdirectory can be moved and if all the pages in it have relative links then those will not break. Absolute links assist in moving pages around since the links on a single page do not break if a single page is moved.

You can put static files in the same directory structure. If the page specifics/coolstory.md has an image tag like ![my alt text](impressive.png), this will get rendered as https://some.site/specifics/impressive.png.

Only .md (markdown) files will be treated like pages. Everything else is won't get rendered like a page (fancy headers, etc).

Inside of your .md files, you can add some front-matter. For example, if you want the title in the browser tab and breadcrumbs to be different from whatever is in the content of the page, you could do:

---
title: This is the title that I like in the browser tab
---
# This is the title that gets displayed as an H1 on the page.

Bacon ipsum dolor sit amet...

The first H1 tag will be used as the name of the page in navigtion.

arxiv-docs uses mkdocs-material which is theme for mkdocs. For information about customizing themes, CSS or JS see:

https://squidfunk.github.io/mkdocs-material/customization/

TODO

TODO: right now there we don't have redirects setup.

mkdocs build leaves a static site in ./site This is a static site with relative links that can be served with any system that hosts a web site.

The cloud build YAML files combined with CloudBuild triggers in arxiv-production comprise the deployment pipeline for arxiv-docs.