From 078d46847b49b6e4ae7827e1a40cb7e9a8895ac9 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Fri, 14 Nov 2025 22:23:19 +0000 Subject: [PATCH] Explain how to use Notebooks instead of Markdown in materials --- .gitignore | 2 ++ for-instructors/style-guide.md | 14 +++++++++++++- myst.yml | 2 +- 3 files changed, 16 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index b879f81..597de64 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ +# Jupyter ephemera +.ipynb_checkpoints # pixi environments .pixi diff --git a/for-instructors/style-guide.md b/for-instructors/style-guide.md index 7b2b7b7..f5d01a1 100644 --- a/for-instructors/style-guide.md +++ b/for-instructors/style-guide.md @@ -33,8 +33,20 @@ Diátaxis is a fantastic resource for writing documentation for various audience Goal: Provide in-depth understanding of a concept, often linking multiple concepts together or explaining a technical decision, architecture, or history. +## Repository structure -## Structure +### Notebooks vs. Markdown + +Notebooks and Markdown can be used interchangeably. +This means the content for your module can be stored in `index.md` or `index.ipynb`. + +Supporting Notebooks can be stored as neighbors to your index file, and your Notebooks +can link to each other. +When participants open the Notebooks in JupyterLab they can click the links to +automatically open other Notebooks. + + +## Content structure All modules should have a consistent structure! diff --git a/myst.yml b/myst.yml index 56eb43a..8741253 100644 --- a/myst.yml +++ b/myst.yml @@ -16,7 +16,7 @@ project: - pattern: "0*.md" - title: "Modules" children: - - pattern: "modules/0*/index.md" + - pattern: "modules/0*/index.{md,ipynb}" - title: "Reference" children: - pattern: "reference/*.md"