Instill is a single-page article template geared towards academics looking to create an online version of their paper. Visit the demo here: https://instill-article.github.io
- Write articles in Markdown! Parsing done by markdown-it
- Katex support thanks to markdown-it-katex
- Table of contents for your articles with markdown-it-toc-done-right
- Include and cite bibtex references with a custom
cite
command; e.g.<cite>someone1992</cite>
- Citations come with a modal that shows more info when clicked on
- Write footnotes that show up in a modal with
<footnote>Lorem ipsum dolor...</footnote>
- Lazy loaded images as suggested here
- Syntax highlighting for code blocks with highlight.js
- SEO tags (OpenGraph and Twitter) included
- Liquid / liquidjs template and CSS stylesheet if you really want to dig into customization π
- CSS autoprefixing for browser compatibility
- HTML+CSS minifier for final page output (though honestly, the page is already tiny π)
- Pure HTML+CSS output (JavaScript is only used for generating the site)
- Yes, even the modals are HTML+CSS π
- Integration with GitHub Actions to deploy to a GitHub Pages site.
To use Instill, start by clicking the
Use this template
button on the home page of the repo, or by visiting this link. Then do the following:
- Check that the license agrees with you. If this work is not under CC-BY-4.0, you will need to change the
LICENSE
, modify the license statement at the bottom ofsrc/index.liquid
, and switch the "license" field inpackage.json
.- Edit the "name", "author", "description", and "repository" fields in
package.json
.- Install dependencies with
npm install
. It is probably a good idea to try firing up the live server withnpm start
.- Modify the fields in
src/data.yaml
.- Replace the following images now or later:
- The OpenGraph preview image in
src/assets/img/open-graph-preview.png
. Recommended resolution is 1200x630.- The Twitter preview image in
src/assets/img/twitter-preview.png
. Recommended resolution is a square image from 144x144 to 4096x4096.- The favicon in
src/favicon.ico
. If you are unfamiliar with favicons, I recommend using an online favicon converter.- The repository is designed to deploy to a GitHub Pages site on an external repo. Typically, I do this by creating an organization so that I can have a URL like
custom-name.github.io
. Once you have such a repo, set up GitHub Actions deployment:
- Obtain a Personal Access Token.
- Add the token as a secret called
TOKEN
(how to add a secret)- Change the
external_repository
(and maybe also thepublish_branch
) at the bottom of.github/workflows/deploy.yaml
.- Remove this blockquote section from the README (but keep the rest of it for your use).
- You're now ready to write your article! The article content is in
src/article.md
, while the references are insrc/references.bib
. See the instructions below for more info.
- Instill knowledge into others by using this template to write an article.
- Much of this template was inspired by Distill.
Install dependencies with:
npm install
Build the site for deployment with:
npm run build
The site will now be available in build/
. Open build/index.html
with your
browser to view the site.
Start the dev server with:
npm start
And view the site at https://localhost:3000.
The main article text is in src/article.md
. Normal Markdown features apply.
In addition:
- When creating an image, such as with
![Alt text](path/to/img.jpg)
, the alt text will be used as the image caption, and will appear below the image when rendered. - You can write footnotes with
<footnote>This is a footnote</footnote>
. - You can cite references in
src/references.bib
with<cite>KEYS</cite>
whereKEYS
is a comma-separated list of keys/ids fromsrc/references.bib
. For instance, you can use<cite>Einstein1921, Oppenheimer1950"</cite>
to cite two articlesEinstein1921
andOppenheimer1950
.- Make sure to include the
url
field in your bibtex entries so that the articles are easily accessible from the webpage.
- Make sure to include the
The article is loaded in a liquidjs template in src/index.liquid
. Any
variables in src/data.yaml
will be passed to this template, except for
styles
and article
(those are reserved). You can also modify the CSS in
src/styles.css
. If you plan to change the appearance completely, note that the
404 page has its own inline styling, so you will want to modify that too.
src
βββ index.liquid -> Liquid page template; variables are loaded in Gulpfile.js
βββ data.yaml -> Data passed to the template
βββ article.md -> Main article text
βββ appendix.md -> Appendix (Acknowledgements, Author Contributions, etc.)
βββ references.bib -> Bibtex references, can be used in the article
βββ styles.css -> Custom CSS styles, loaded into the head of the final page
βββ assets/ -> Additional JS, CSS, images
βββ robots.txt -> Defaults to doing nothing
βββ favicon.ico -> Default is just an X
βββ 404.html
The article in this repository is released under the CC-BY-4.0 License, and the infrastructure code is released under the MIT License.
This article is built with the Instill template by Bryon Tjanaka.