Skip to content

Commit 23475f8

Browse files
giswqsgiswqs
authored
Improve blog layout (#5)
1 parent 5d77672 commit 23475f8

7 files changed

Lines changed: 575 additions & 65 deletions

File tree

‎blog/myst-article-template.md‎

Lines changed: 279 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,279 @@
1+
---
2+
title: "Write Journal Articles with MyST Markdown: Auto-Generate PDFs and Websites"
3+
date: 2026-04-15
4+
authors:
5+
- name: Qiusheng Wu
6+
email: qwu18@utk.edu
7+
orcid: 0000-0001-5437-4073
8+
url: https://gishub.org
9+
description: A step-by-step tutorial on writing journal articles in MyST Markdown with automatic PDF generation and website deployment using a GitHub template.
10+
thumbnail: https://img.youtube.com/vi/iwL-s7aPNYQ/maxresdefault.jpg
11+
tags:
12+
- MyST Markdown
13+
- GitHub Pages
14+
- Tutorial
15+
- PDF
16+
- Academic Writing
17+
keywords:
18+
- MyST Markdown
19+
- GitHub Pages
20+
- Tutorial
21+
- PDF
22+
- Academic Writing
23+
- Journal Articles
24+
- Jupytext
25+
---
26+
27+
# Write Journal Articles with MyST Markdown: Auto-Generate PDFs and Websites
28+
29+
Writing journal articles usually means choosing between tools that are easy to use and tools that produce professional output. Google Docs and Microsoft Word are simple but give you limited control over formatting and make collaboration through version control difficult. LaTeX produces beautiful PDFs but has a steep learning curve. What if you could write in plain Markdown, push to GitHub, and get both a publication-quality PDF and an interactive website generated automatically? That is exactly what the [myst-article-template](https://github.com/opengeos/myst-article-template) provides.
30+
31+
In this tutorial, I walk through the entire workflow step by step: creating a repository from the template, editing your article content, managing citations, adding figures and tables, including executable code blocks, generating a PDF, and deploying everything as a website. The whole process takes just a few minutes to set up.
32+
33+
:::{iframe} https://www.youtube.com/embed/iwL-s7aPNYQ
34+
:width: 100%
35+
Video tutorial: Write Journal Articles with MyST Markdown
36+
:::
37+
38+
## What You Will Need
39+
40+
- A [GitHub](https://github.com) account (free).
41+
- For local editing and preview: a code editor like [VS Code](https://code.visualstudio.com) or [Cursor](https://cursor.com), [Node.js](https://nodejs.org) (version 18 or later), and Python 3.
42+
- For local PDF compilation: the [Typst](https://typst.app) CLI (optional, since GitHub Actions handles this automatically).
43+
44+
## What the Template Produces
45+
46+
Before diving into the setup, here is what you get out of the box:
47+
48+
- **A publication-ready PDF** with title, authors, affiliations, section headings, figures, tables, code blocks, and a full reference list. You can view a [sample PDF](https://opengeos.org/myst-article-template/article.pdf) to see the output quality.
49+
- **An interactive website** deployed to GitHub Pages with hover-to-preview citations, clickable cross-references, and expandable code blocks. See the [demo website](https://opengeos.org/myst-article-template) for a live example.
50+
51+
The PDF and the website are both generated from the same Markdown source. You write once and get both outputs automatically whenever you push changes to GitHub.
52+
53+
## Create Your Repository from the Template
54+
55+
1. Go to the [myst-article-template](https://github.com/opengeos/myst-article-template) repository on GitHub.
56+
2. Click the green **Use this template** button in the upper right corner, then select **Create a new repository**.
57+
3. Choose your GitHub account as the owner and give the repository a name, for example `my-article`.
58+
4. Optionally add a description like "Repository for my journal article."
59+
5. Click **Create repository** and wait a few seconds for GitHub to copy the template.
60+
61+
## Enable GitHub Pages
62+
63+
The first deployment will fail because GitHub Pages is not enabled by default. To fix that:
64+
65+
1. Go to your new repository's **Settings** tab.
66+
2. In the left sidebar, click **Pages**.
67+
3. Under **Build and deployment**, change the source to **GitHub Actions**.
68+
4. Go back to the **Actions** tab. Click into the failed workflow run, then click **Re-run failed jobs** to trigger a fresh build.
69+
5. After a minute or two, your site will be live at `https://username.github.io/repo-name`.
70+
71+
To make the URL easy to find, go to the repository's **About** section (gear icon on the main page), check **Use your GitHub Pages website**, and save.
72+
73+
## What GitHub Actions Does for You
74+
75+
Every time you push changes to the repository, the GitHub Actions workflow automatically:
76+
77+
1. Builds the HTML website with `myst build --html`.
78+
2. Generates the article PDF.
79+
3. Deploys everything to GitHub Pages.
80+
81+
The PDF is always available at a stable URL: `https://username.github.io/repo-name/article.pdf`. You can share this link directly, and it will always point to the latest version of your article.
82+
83+
## Clone and Edit Locally
84+
85+
Clone the repository to your local machine and open it in your editor:
86+
87+
```bash
88+
git clone https://github.com/username/repo-name.git
89+
cd repo-name
90+
```
91+
92+
Install the Python dependencies:
93+
94+
```bash
95+
pip install -r requirements.txt
96+
```
97+
98+
Start the local development server to preview your article:
99+
100+
```bash
101+
myst start
102+
```
103+
104+
This launches a preview at `http://localhost:3000` (or a similar port). Changes to your Markdown files are reflected in the browser automatically. For a side-by-side editing experience, split your editor window and open the preview URL in the built-in browser panel. Every time you save a file, the preview updates instantly.
105+
106+
## Update Article Metadata
107+
108+
The article content lives primarily in `article.md`. Open this file and update the frontmatter at the top:
109+
110+
- **Title**: Update the article title. Note that the title is also referenced in `myst.yml`, so update it in both places to keep the PDF and website consistent.
111+
- **Authors**: Replace the template author names with your own. Each author entry supports `name`, `email`, `affiliations`, and other fields.
112+
- **Affiliations**: Update department, institution, city, and country.
113+
- **Subtitle**: If your article has a subtitle, you can add it in `myst.yml` under the project configuration.
114+
115+
The author and affiliation information appears in the PDF header. The website pulls its metadata from the same source, so you only need to update it once.
116+
117+
## Manage Citations
118+
119+
MyST Markdown makes citation management straightforward. All references are stored in a `references.bib` file using standard BibTeX format.
120+
121+
### Add a New Reference
122+
123+
1. Find the article you want to cite on [Google Scholar](https://scholar.google.com) or your preferred source.
124+
2. Click the **Cite** button, then select **BibTeX** to get the formatted entry.
125+
3. Copy the BibTeX entry and paste it into `references.bib`.
126+
4. Optionally add a `doi` field if one is available. Make sure each entry has a unique citation key (the identifier after `@article{`).
127+
128+
### Cite in Your Article
129+
130+
MyST supports two citation styles:
131+
132+
- **Parenthetical citation**: `[@article-id]` renders as (Author, Year).
133+
- **Narrative citation**: `@article-id` renders as Author (Year).
134+
135+
On the website, citations are interactive. Hovering over a citation shows the full reference in a tooltip, and clicking it scrolls to the reference list. In the PDF, citations are hyperlinked to the bibliography section.
136+
137+
### Add a DOI
138+
139+
To include a DOI in your reference, add a `doi` field to the BibTeX entry in `references.bib`:
140+
141+
```bibtex
142+
@article{wu2020geemap,
143+
title={geemap: A Python package for interactive mapping with Google Earth Engine},
144+
author={Wu, Qiusheng},
145+
journal={Journal of Open Source Software},
146+
year={2020},
147+
doi={10.21105/joss.02305}
148+
}
149+
```
150+
151+
Make sure to include only the DOI identifier (e.g., `10.21105/joss.02305`), not the full URL. Also ensure there is a comma after every field in the BibTeX entry, as a missing comma will cause a build error.
152+
153+
## Add Figures, Tables, and Code
154+
155+
### Tables
156+
157+
You can create tables using standard Markdown table syntax. The template also supports the three-line table format commonly used in academic publishing:
158+
159+
```markdown
160+
:::{table} Overview of Methods
161+
:label: tbl-methods
162+
163+
| Method | Accuracy | Speed |
164+
|--------|----------|-------|
165+
| Method A | 95.2% | Fast |
166+
| Method B | 97.1% | Moderate |
167+
| Method C | 93.8% | Fast |
168+
:::
169+
```
170+
171+
Tables are automatically numbered. To reference a table elsewhere in your article, use `` {numref}`tbl-methods` ``, which renders as "Table 1" (or whatever the sequential number is). You never need to manually track table numbers.
172+
173+
### Figures
174+
175+
Figures work similarly. Add an image with a label and caption:
176+
177+
```markdown
178+
:::{figure} ./images/study-area.png
179+
:label: fig-study-area
180+
:alt: Map of the study area
181+
182+
Map showing the study area boundary and sample locations.
183+
:::
184+
```
185+
186+
Reference figures with `` {numref}`fig-study-area` `` to get automatic numbering. On the website, hovering over a figure reference shows a preview of the figure in a tooltip, which is especially useful when the figure is on a different page or section of a long article.
187+
188+
### Code Blocks
189+
190+
One of the most powerful features of MyST Markdown is support for executable code blocks. You can include source code that readers can view, and on the website, interact with:
191+
192+
````markdown
193+
```{code-block} python
194+
import geoai
195+
196+
m = geoai.Map()
197+
m
198+
```
199+
````
200+
201+
Code blocks appear in both the PDF and the website. On the website, they are syntax-highlighted and can be expanded or collapsed. This is particularly valuable for research articles that include data analysis or visualization code, making your work fully reproducible.
202+
203+
## Generate the PDF Locally
204+
205+
You do not need to generate the PDF locally since GitHub Actions handles it on every push. But if you want to preview the PDF before pushing:
206+
207+
```bash
208+
python build_pdf.py
209+
```
210+
211+
This runs the build script and produces `article.pdf` in the project root. Open it to verify that your title, authors, affiliations, citations, figures, tables, and code blocks all render correctly.
212+
213+
## Convert Between Markdown and Jupyter Notebooks
214+
215+
If your article contains executable code, you may want to run it interactively in a Jupyter notebook. The template supports [Jupytext](https://jupytext.readthedocs.io), which converts between MyST Markdown and Jupyter notebook formats.
216+
217+
### Markdown to Notebook
218+
219+
Convert your article to a Jupyter notebook:
220+
221+
```bash
222+
jupytext --to ipynb article.md
223+
```
224+
225+
This creates `article.ipynb` with all your code cells ready to execute. Open it in Jupyter or VS Code, select a kernel, and run the cells to verify your code produces the expected output.
226+
227+
### Notebook to Markdown
228+
229+
After editing or running code in the notebook, sync changes back to Markdown:
230+
231+
```bash
232+
jupytext --to myst article.ipynb
233+
```
234+
235+
One thing to keep in mind: converting back to MyST Markdown can sometimes simplify the frontmatter. Use version control (`git diff`) to review the changes and make sure no metadata was lost. It is a good practice to commit your Markdown changes before converting to a notebook, so you can always restore the original frontmatter if needed.
236+
237+
## Deploy and Verify
238+
239+
Once you are happy with your changes, commit and push to GitHub. For small updates, you can push directly to the `main` branch:
240+
241+
```bash
242+
git add .
243+
git commit -m "Update article content"
244+
git push
245+
```
246+
247+
For larger changes, create a feature branch and open a pull request:
248+
249+
```bash
250+
git checkout -b update-article
251+
git add .
252+
git commit -m "Update article content"
253+
git push -u origin update-article
254+
```
255+
256+
Then create a pull request on GitHub. The template includes pre-commit hooks that catch common issues like typos, trailing whitespace, and formatting problems. Once the pull request checks pass, merge it into `main` and the updated website and PDF will be deployed automatically.
257+
258+
After deployment, verify both outputs:
259+
260+
- **Website**: Visit `https://username.github.io/repo-name` and check that your content, citations, figures, and tables render correctly.
261+
- **PDF**: Navigate to `https://username.github.io/repo-name/article.pdf` and confirm the layout, references, and formatting.
262+
263+
## Why This Approach Works
264+
265+
Because everything is stored as plain text Markdown in a GitHub repository, you get several advantages over traditional document editors:
266+
267+
- **Version control**: Every change is tracked. You can always go back to a previous version if something goes wrong, which is far more reliable than the revision history in Google Docs or keeping multiple copies of a Word document.
268+
- **Collaboration**: Multiple authors can work on the same article using branches and pull requests, with clear diffs showing exactly what changed.
269+
- **Reproducibility**: Executable code blocks mean readers (and reviewers) can verify your analysis directly from the article.
270+
- **Accessibility**: The web version of your article is publicly accessible without requiring readers to download attachments.
271+
- **Focus on content**: You write in Markdown and let the tooling handle layout, numbering, citation formatting, and PDF compilation.
272+
273+
## What is Next
274+
275+
This tutorial covers the complete workflow from template to deployed article with automatic PDF generation. If you are interested in building a personal academic website using the same technology stack, check out [Build a Personal Website in 5 Minutes: No Coding Required](./build-personal-website). For a website that also includes automatic CV generation, see [Build a Professional CV Website with Auto PDF Generation Using MyST Markdown](./myst-cv-website).
276+
277+
The [MyST Markdown guide](https://mystmd.org/guide) is the best reference for all available directives and components. For customizing the PDF output, the [Typst documentation](https://typst.app/docs) covers layout and typography options.
278+
279+
If you use this template for your next article, feel free to share it on social media. I would love to see what you publish!

0 commit comments

Comments
 (0)