Skip to article frontmatterSkip to article content

Open Publishing

Workshop Description

Open publishing enhances accessibility, transparency, and reproducibility in research. This workshop introduces participants to open publishing principles and practical tools for creating interactive and reproducible scientific documents. Participants will learn how to use Jupyter Book and MyST Markdown to develop and publish open research content efficiently.

This session is ideal for researchers, educators, and students looking to improve their scientific communication. No prior experience with Jupyter Book or MyST Markdown is required, making it accessible to beginners.

Learning Outcomes

By the end of the workshop, participants will be able to:

Format

This is an interactive, hands-on workshop. Participants will follow along with demonstrations and practice key concepts through guided exercises.

Prerequisites

To ensure a smooth learning experience, participants are encouraged to install the following tools before the workshop:

Date and Time

Instructor

Who Should Attend?

This workshop is ideal for:

No prior experience with Jupyter Book or MyST Markdown is required.

Registration

To attend, please complete the registration form at this link. Once registered, you will receive a confirmation email with the Zoom link and preparation instructions.

Workshop Recording

A recording of the workshop will be available on the Open Geospatial Solutions YouTube channel after the event.

Introduction to Open Publishing

Why Open Publishing?

Tools for Open Publishing

Workshop Modules

Module 1: Setup and Environment

Module 2: Basic Document Structure

Module 3: Interactive Documents

Module 4: Publishing and Distribution

Detailed Schedule

Module 1: Setup and Environment

Setup Instructions

# Create and activate conda environment
conda create -n myst-workshop python=3.12
conda activate myst-workshop

# Install required packages
conda install -c conda-forge mystmd
conda install -c conda-forge texlive-core latexmk jupyterlab-myst ipykernel

# Verify installation
myst -v

VS Code Extension: Install MyST-Markdown

Your First MyST Project

# Clone starter template
git clone https://github.com/jupyter-book/mystmd-quickstart.git
cd mystmd-quickstart

# Start the MyST server
myst start

Core MyST Commands

# Initialize a new project
myst init

# Start the preview server (with execution)
myst start --execute

# Clean build files
myst clean
myst clean --all
myst clean --templates --cache

Module 2: Basic Document Structure

Project Configuration

Edit myst.yml:

# See docs at: https://mystmd.org/guide/frontmatter
version: 1
project:
  id: ab440adc-2db2-4534-8548-ad2b03879434
  title: Introduction to GIS Programming
  github: https://github.com/jupyter-book/mystmd-quickstart
site:
  template: book-theme
  options:
    favicon: images/favicon.ico
    logo: images/logo.png

Page Frontmatter

---
title: Introduction to GIS Programming
subtitle: Using Python for GIS Applications
authors:
  - name: Your Name
    affiliations:
      - Your University
    orcid: 0000-0000-0000-0000
    email: your.email@example.com
license: CC-BY-4.0
keywords: GIS, python, geospatial, mapping
abstract: |
  This tutorial introduces geospatial analysis techniques using Python libraries and demonstrates how to effectively visualize and analyze geographic data.
kernelspec:
  name: python3
  display_name: Python 3
---

Adding Citations

To cite using DOI:

Change (Smith et al., 2020) to [](https://doi.org/10.XXXX/XXXXX)

To cite using BibTeX:

{cite:p}`myst2023,jupyterbook2021`

Figures and Images

Basic figure:

:::{figure} ./images/map.png
:label: my-map-figure
:alt: GIS map showing population density
:align: center

Map showing population density in the study area.
:::

Remote image with alignment:

:::{figure} https://example.com/path/to/image.png
:align: right
:width: 40%

Caption for the figure.
:::

Cross-references

Reference a figure:

See [](#my-map-figure) for the spatial distribution.

Module 3: Interactive Documents

Adding Code Cells

In a Markdown file:

```{code-cell}
:label: simple-map
import geopandas as gpd
import matplotlib.pyplot as plt

# Load example data
world = gpd.read_file(gpd.datasets.get_path('naturalearth_lowres'))

# Plot
fig, ax = plt.subplots(figsize=(10, 6))
world.plot(ax=ax)
plt.title('World Map')
plt.axis('off')

Adding Labels to Code Cells

In notebooks:

#| label: population-map
import geopandas as gpd
world = gpd.read_file(gpd.datasets.get_path('naturalearth_lowres'))
world.plot(column='pop_est', legend=True)

Then reference:

See the population distribution map in [](#population-map).

Executing Notebooks

Make sure to add this to frontmatter:

kernelspec:
  name: python3
  display_name: Python 3

Then run:

myst start --execute

Interactive Elements

Create a dropdown:

:::{note} Solution to Exercise 1
:class: dropdown
Here we see that the spatial autocorrelation is positive with a Moran's I value of 0.68.
:::

Module 4: Publishing and Distribution

Exporting to Various Formats

For Word documents:

---
exports:
  - format: docx
---

For PDF:

---
exports:
  - format: pdf
    template: volcanica
    article_type: Report
---

For LaTeX:

---
exports:
  - format: tex
    template: volcanica
    article_type: Report
    output: arxiv.zip
---

Build command:

myst build your_document.md

Deploying to GitHub Pages

  1. Run myst init --gh-pages
  2. Modify workflow file:
jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - uses: actions/setup-node@v4
        with:
          node-version: 18.x
      - name: Install MyST Markdown
        run: |
          npm install -g mystmd
          pip install -r requirements.txt
          pip install ipykernel
          python -m ipykernel install --user
      - name: Build HTML Assets
        run: myst build --html --execute
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: "./_build/html"
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
  1. Create a new GitHub repository
  2. Push your content
  3. Enable GitHub Pages in repository settings

Managing Table of Contents

Update TOC:

myst init --write-toc

Customize TOC:

toc:
  - file: README.md
  - file: 01-introduction.md
  - title: Geospatial Analysis
    children:
      - file: chapters/spatial-data.ipynb
      - file: chapters/visualization.ipynb

Enable section numbering:

project:
  numbering:
    heading_1: true
    heading_2: true

Demos

Resources & Further Reading

This hands-on workshop will equip participants with the skills to create, automate, and publish open, interactive, and reproducible scientific content using Jupyter Book, MyST Markdown, and GitHub.

Happy coding! 🎉

Open Science Workshop
Open Results
Open Science Symposium
Spring 2025