This project implements a markdown-driven static site for arXiv help documentation.
Each site should be contained in a single directory. For example:
mysite/
├── index.md
├── specifics/
| ├── impressive.png
| └── coolstory.md
└── _templates
└── mysite
└── custom.html
Custom templates go in _templates/<SITE NAME>.
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. But note that the file
foo/baz/index.md will be served at https://some.site/foo/baz.
Everything is relative. You can add a link in foo/baz/index.md
like [click here for cool](bat), and the link will be rendered as
https://some.site/foo/baz/bat.
You can put static files in the same directory structure. If the page
specifics/coolstory.md has an image tag like
, this will get rendered as
https://some.site/specifics/impressive.png. In other words, it will just
work.
Only .md (markdown) files will be treated like pages. Everything else is
general static content and 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...You can add custom templates (otherwise a generic arXiv template gets used,
with nice breadcrumbs). For example, in one of your pages you could choose to
use the template at _templates/mysite/custom.html by setting the
frontmatter:
---
template: mysite/custom.html
---You'll need Docker to do this.
To build the arXiv docs site, run:
docker build . -t arxiv/docs:mytagYou should see lots of things happening, and maybe this will take a few minutes if you have a big site. At the end, you should see something like:
Successfully built 297b169df71f
Successfully tagged arxiv/docs:mytagYou can then run the site by doing:
docker run -it -p 8000:8000 arxiv/docs:mytagIn your browser, go to http://localhost:8000/about (or whatever page you want).
You can access the search page at <SITE_URL_PREFIX>/search.
You can control the HTTP response to the user's agent using the response
key in the frontmatter. The following parameters are supported:
| Parameter | Type | Default | Description |
|---|---|---|---|
response.status |
int | 200 |
The HTTP status code for the response. |
response.location |
str | None | Sets the Location header; this can be used to redirect the user. |
response.deleted |
bool | false |
If true, a status code of 404 will be returned, and a special "deleted" template will be rendered. |
---
response:
deleted: true
---
This page was deleted because it was not that great.
---
response:
status: 301
location: the/new/location
---
As of marXdown 0.2.1, multiple sites can be served in the same uWSGI process, and therefore in a single Docker container with a single entrypoint. This saves a lot of resources on overhead, especially for low-traffic sites.
Since marXdown relies heavily on start-up configuration, however, the trade-off is that (a) we need to use configuration files to keep configs separate for each app rather than using environment variables, and (b) that means we need to be able to define the Flask "instance path" at app creation time (i.e. before configuration) which means that we need a custom WSGI entrypoint for each app.
Places where relevant paths and parameters are defined:
deploy/[site]/wsgi.pyis the custom WSGI entrypoint for the site/app. This gets added at/opt/arxiv/[site]/wsgi.pyin the Docker image.deploy/[site]/instance/application.cfgis a Python script with config parameters. This gets added at/opt/arxiv/[site]/instance/application.cfgin the Docker image.Dockerfileis where all of the above gets added to the Docker image, and the build script for each site/app is invoked.
We use the arxiv/marxdown Helm chart to deploy to Kubernetes. See