HaskellStack.org¶
The domain https://docs.haskellstack.org hosts online documentation for the Stack project, using Read the Docs with MkDocs and the Material for MkDocs theme.
The domain https://get.haskellstack.org provides URLs that redirect to URLs used to install the Stack executable.
Read the Docs¶
The Read the Docs project is named 'The Haskell Tool Stack'.
The set up on the Read the Docs web site involves two page redirects when there are HTTP 404 Not Found errors:
/ -> /README/
/README/ -> /
The 'Home' MkDocs page is doc/README.md
.
The / -> /README/
redirect ensures that
https://docs.haskellstack.org/en/stable/ (for example) will, if not found,
redirect to https://docs.haskellstack.org/en/stable/README/.
The /README/ -> /
redirect ensures that
https://docs.haskellstack.org/en/latest/README/ (for example) will, if not
found, redirect to https://docs.haskellstack.org/en/latest/.
MkDocs rendering of README.md
differed before and after MkDocs 1.0. Prior to
MkDocs 1.0, README.md
rendered to /README/index.html
. From MkDocs 1.0,
README.md
rendered to /index.html
. The two redirects above ensure that the
Read the Docs flyout works when moving between different versions of the home
page using the flyout.
Stack moved from MkDocs 0.17.3 to MkDocs 1.3.1 after publishing the documentation for Stack 2.7.5.
A YAML configuration file, .readthedocs.yaml
is included in the repository
root directory. See https://docs.readthedocs.io/en/stable/config-file/v2.html.
It specifies a Python requirements file in doc/requirements.txt
.
MkDocs¶
The doc/requirements.txt
file pins the version of MkDocs. As at
2 September 2021 it is set to:
mkdocs==1.3.1
A YAML configuration file, mkdocs.yml
is included in the repository root
directory. See https://www.mkdocs.org/user-guide/configuration/.
site_dir: _site
specifies the directory where the output HTML and other files
are created. This directory is added to the .gitignore
file.
MkDocs 1.3.0 replaced the pages:
key with the nav:
key.
Material for MkDocs¶
Stack moved from the default readthedocs
theme to Material for MkDocs after
publishing the documentation for Stack 2.7.5. The new theme has extensive online
documentation and features that the default theme lacked.
The Material for MkDocs theme is loaded in the doc/requirements.txt
file:
mkdocs-material
The theme is specified in the mkdocs.yml
file:
theme:
name: material
palette:
primary: 'deep purple'
accent: 'deep purple'
icon:
logo: material/language-haskell
Read the Docs requires JQuery for its JavaScript code to
inject the flyout menu. Material for MkDocs does not come with JQuery. So, the
following is required in the mkdocs.yml
file:
The Read the Docs flyout is formatted with a font-size
that is 90% of the
body
font-size
. Material for MkDocs has a body
font-size
that is
0.5rem
, which is small. A little additional CSS is added to the extra.css
file, to force the final font-size
to be 0.7rem
. That size is consistent
with that of other elements in the theme.
Material for MkDocs default suggestions for syntax highlighting in code blocks
are applied. They are specified in the mkdocs.yml
file as:
markdown_extensions:
- pymdownx.highlight:
anchor_linenums: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.superfences
Other extensions to the basic Markdown syntax used include:
-
Admonitions
Info
This is an example of an 'info' admonition.
-
Content tabs, which can be nested
Info
Content tabs are used so that users of different operating systems, or different distributions of Linux, can be presented with content specific to their needs.
-
icons and emojis
Info
The
octicons-tag-24
icon () is used to refer to versions of Stack. Thematerial-cloud-download-outline
icon () is used to signify a download link. Theocticons-beaker-24
icon () is used with 'Experimental' to signify that a feature is experimental.
Testing online documentation¶
Online documentation can be tested by establishing a branch on the repository
that is then configured on the Read the Docs web site as 'Active' but
'Hidden' - for example branch mkdocs-test
. As the branch is 'Hidden' it does
not appear in the Read the Docs flyout or search results.
get.haskellstack.org redirects¶
The https://get.haskellstack.org redirects are implemented with
CloudFlare Pages
and a _redirects
file in the root of the
commercialhaskell/get-haskellstack-org
GitHub
repository.
Each redirect is defined as a line in the file with format:
'Splats' are used in redirects. On matching, a splat (asterisk, *
) will greedily match all characters and the matched value can be used in the redirect location with :splat
.
For example, for Stack 2.9.1:
/stable/* https://github.com/commercialhaskell/stack/releases/download/v2.9.1/stack-2.9.1-:splat
/upgrade/linux-x86_64-static.tar.gz https://github.com/commercialhaskell/stack/releases/download/v2.9.1/stack-2.9.1-linux-x86_64.tar.gz
/upgrade/* https://github.com/commercialhaskell/stack/releases/download/v2.9.1/stack-2.9.1-:splat
/ https://raw.githubusercontent.com/commercialhaskell/stack/stable/etc/scripts/get-stack.sh