in-progress manuscript.
Rendered at https://jon-e.net/infrastructure
TODO
We're using gitter (which recently became a Matrix client) to chat, organize the paper, as well as have continuing dialogue after release.
TODO
- normal markdown,
{% cite bibtex-key %}
for citations- what else !??!?
- The document is built using jekyll and also includes some page elements built using react.
- The
package.json
file contains the scripts used to build and serve the document (described below) - Dependency management and building uses
- yarn to manage node/javascript dependencies (for react). Yarn reads the dependencies in
package.json
and makes theyarn.lock
file which is a full snapshot of exact dependencies used in the last installation. - bundler to manage the ruby dependencies. Bundler uses the
Gemfile
to generate theGemfile.lock
analogously to yarn. - webpack to compile React and other javascript into an included bundle
- yarn to manage node/javascript dependencies (for react). Yarn reads the dependencies in
(all .md
or .markdown
files are rendered to html, so index.markdown
becomes index.html
on the final site.)
index.markdown
is the parent file that structures the document and imports its different sections._sections/
contains each of the sections included into the main document. The sections are numbered, but refer to the index for the definitive ordering.assets/infrastructure.bib
- a BibTeX file containing all references in the piece, add new references here and cite them with the@key
.
todo.md
- keeping track of things to dotrims.markdown
- large sections of text removed from the main text to try and make it shorter that might find their way into future writing (see_trims/
)
_includes/
- short liquid templates to use in page_layouts/
- whole-page layout templates to structure html, see the header of each .md/.markdown file_plugins/
- jekyll plugins_sass/
- compiled to css, control the look and feel of the site.
assets/
has vanilla css and javascript, as well as all any imagesassets/notebooks
will eventually be included in the document, but the rendering is turned off at the moment while it's being debugged.
tex/
see pdf-renderingcode
contains supplementary code for calculating numbers for the paper/other meta-needs.data
contains any data referenced in the text.
You will first need to have installed
- node (working version: 17.2.0)
- yarn (working version: 1.22.17)
- ruby (working version: 3.0.2p107)
- bundler (working version: 2.2.29)
On macOS:
# install homebrew if needed
# /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install node yarn ruby
gem install bundler
Let me know of any other OS needs by raising an issue!
Clone the repository and enter the directory
git clone https://github.com/sneakers-the-rat/infrastructure
cd infrastructure
Install the ruby and node dependencies
bundle install
yarn install
The build is in two stages, first webpack runs to compile the React and other javascript into a bundle, and then jekyll compiles the markdown, scss, and javascript into the final website. The website is built into the _site
directory
npm run build
which just calls
npm run build_wp
npm run build_jk
To write locally, you can run a development server which continuously rebuilds the page whenever the files are updated.
The local version is identical to the published version, except that hypothes.is is currently disabled locally by default because the bug that's slowing down the page on load is really excruciating with constant rebuilds and refreshes. I've opened an issue
Start the development server with
npm run start
and then open http://127.0.0.1:4000/infrastructure/
in your browser.
When a new commit is pushed to main
, the website is built with github actions (see .github/workflows/github-pages.yml
) and deployed on the gh_pages
branch, which is what https://jon-e.net/infrastructure points to.
The script code/jekyll_to_tex.py
converts the markdown to TeX. This part is currently under construction and not part of the automated build pipeline!
It uses pandoc and a pile of manual syntax conversion to make tex/decentralized_infrastructure_render.tex
, which uses styles from tex/jls_base.sty
.
The .pdf version may lag behind the site by several commits, and doesn't have the same versioning and metadata at the moment, but it is provided for choice of medium, and will be what is submitted to bioRxiv.
Every time a new version is committed to main
, the github action also stores a versioned build identified by the short 7-digit hash. They can be found at the url pattern https://jon-e.net/infrastructure/versions/<HASH>/
, for example https://jon-e.net/infrastructure/versions/b7a7676/.
These versions, to the degree that they differ from the current version, might have their hypothesis annotations all over the place, or have other problems patched in later versions. I also warn that I might yank a version before official publication, but will strongly avoid doing so afterwards.
Derivative slideshows can also be made by using the slides
layout, which uses reveal.js for animation.
The syntax is straightforward:
---
layout: slides
title: CMHJC
---
<section>
contents rendered as HTML
</section>
<section data-markdown>
# use markdown syntax!
- make lists
- or whatever **you want**
</section>
and see the reveal.js docs for more.