feat: migrate blog posts from ipynb/md to qmd format

.github/workflows/main.yaml

@@ -33,9 +33,10 @@ jobs:
       cancel-in-progress: true
     defaults:
       run:
-        shell: bash -l {0}
+        # bash -el required so conda activation persists (README: IMPORTANT)
+        shell: bash -el {0}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - uses: conda-incubator/setup-miniconda@v3
         with:
@@ -45,18 +46,26 @@ jobs:
           activate-environment: osl-web
           auto-update-conda: true
           conda-solver: libmamba
+          conda-remove-defaults: true
 
       - name: Install dependencies
         run: |
           poetry check
           poetry install
           python -m nltk.downloader punkt
 
+      # Render blog .qmd → .md so Build uses correct index.md (with YAML)
+      - name: Pre-build blog (quarto + inject)
+        run: makim pages.pre-build
+
+      # Skip mkdocs-build in pre-commit so we don't fail when repo's md != pre-build output
       - name: Linter
         if: ${{ github.event_name == 'pull_request' }}
+        env:
+          PRE_COMMIT_SKIP: mkdocs-build
         run: |
           pre-commit install
-          pre-commit run --all-file --verbose
+          pre-commit run --all-files --verbose
 
       - name: Build the book
         run: |

.gitignore

@@ -128,3 +128,9 @@ dmypy.json
 # Pyre type checker
 .pyre/
 .vscode
+
+/.quarto/
+**/*.quarto_ipynb
+
+# llm
+.codex

.makim.yaml

@@ -5,19 +5,39 @@ groups:
         help: pre-build step
         backend: bash
         run: |
+          set -e
           mkdir -p build
-          # Directory to search for .ipynb files
+          # Directory to search for blog sources
           export SEARCH_DIR="pages/blog"
 
-          # Find all .ipynb files, excluding .ipynb_checkpoints,
-          # and convert them to Markdown named 'index.md'
+          # 1) Convert legacy .ipynb posts to Markdown (for now)
+          #    This keeps existing notebook-based posts working while we
+          #    migrate everything to Quarto.
           find "$SEARCH_DIR" -path "*/.ipynb_checkpoints/*" -prune -o -name \
             "*.ipynb" -exec sh -c \
             'jupyter nbconvert --to markdown --template=theme/custom-markdown.tpl --output-dir "$(dirname "$0")" --output "index" "$0"' {} \;
 
-          # remove console colors from md files
-          find "$SEARCH_DIR" -name \
-            "index.md" -exec sh -c \
+          # 2) Convert .qmd blog posts to Markdown using Quarto
+          #    Run quarto render from inside each blog folder (Quarto rejects --output path).
+          if ! command -v quarto >/dev/null 2>&1; then
+            echo "[EE] Quarto CLI is required but not found on PATH. Install it (e.g. conda install quarto) and retry."
+            exit 1
+          fi
+          mapfile -d "" qmd_files < <(find "$SEARCH_DIR" -name "*.qmd" -print0)
+          for qmd_path in "${qmd_files[@]}"; do
+            dir=$(dirname "$qmd_path")
+            base=$(basename "$qmd_path" .qmd)
+            (
+              cd "$dir"
+              quarto render "$base.qmd" --to gfm -M template=default
+            )
+          done
+
+          # 3) Ensure generated index.md have YAML from .qmd (Quarto may drop it)
+          python scripts/inject-qmd-yaml-into-md.py
+
+          # 4) Remove console colors from generated md files
+          find "$SEARCH_DIR" -name "index.md" -exec sh -c \
             'cat "$(dirname "$0")/index.md" | python scripts/clean-output.py > "$(dirname "$0")/temp_index.md" && mv "$(dirname "$0")/temp_index.md" "$(dirname "$0")/index.md"' {} \;
 
       build:

CONTRIBUTING.md

@@ -42,15 +42,13 @@ dependencies and activate it.
 
 ### Creating a New Blog Post
 
-1. **Prepare the Blog Post:**
+1. **Prepare the Blog Post (Quarto-first workflow):**
 
    - Navigate to `pages/blog` and create a new folder with a slugified version
      of your blog post's title. Use
      [https://slugify.online/](https://slugify.online/) to generate a slug.
-   - Inside this folder, create your blog post file:
-     - For Markdown: `index.md`
-     - For Jupyter Notebooks: `index.ipynb` (use Jupyter Lab to create this
-       directly)
+   - Inside this folder, create your blog post as a **Quarto document**:
+     - `index.qmd`
 
 2. **Include a Header Image:**
    - Place a header image (either `header.png` or `header.jpg`) in your blog
@@ -70,8 +68,8 @@ dependencies and activate it.
 
 ### Metadata and Formatting
 
-- **Markdown Posts:** Add a metadata block at the beginning of your `index.md`
-  file:
+- **Quarto (`.qmd`) Posts:** Add a metadata block at the beginning of your
+  `index.qmd` file:
 
   ```markdown
   ---
@@ -87,20 +85,54 @@ dependencies and activate it.
   ---
   ```
 
-- **Jupyter Notebook Posts:** The first cell of your `index.ipynb` should be in
-  `raw` mode containing the same metadata as above.
+  The body of the file uses standard Markdown plus any Quarto features you need
+  (code chunks, figures, etc.). During the build, `makim pages.build` will
+  render `index.qmd` to `index.md` using Quarto so that MkDocs can consume the
+  generated Markdown.
 
 3. **Building and Viewing:**
-   - If using a Jupyter Notebook, run `makim pages.build` to convert the
-     notebook into a Markdown file (`index.md`).
-   - Add the generated `index.md` to your repository as it will be used to
-     render the webpage.
+   - Run `makim pages.build` to render `index.qmd` to `index.md` and build the
+     site. The generated `index.md` is used to render the webpage.
+
+### Regenerating blog Markdown (for CI)
+
+CI expects the rendered `index.md` files under `pages/blog/*/` to be committed.
+If you change `.qmd` content or metadata, regenerate and push the markdown:
+
+```bash
+# From repo root with conda env active (e.g. on WSL or Linux)
+$ makim pages.pre-build
+$ git add pages/blog/*/index.md
+$ git commit -m "chore: sync rendered blog index.md from qmd"
+$ git push
+```
+
+On Windows, use WSL or a Linux environment so `makim pages.pre-build` (Quarto)
+runs correctly.
+
+### Commit messages
+
+Keep commit messages professional and descriptive. Do not add tool or editor
+tags (e.g. "Made-with: Cursor") to commit messages.
+
+To fix existing commits that contain such a line (e.g. before pushing a PR):
+
+```bash
+# Rebase the last N commits (replace 3 with how many need fixing)
+$ git rebase -i HEAD~3
+# In the editor, change 'pick' to 'reword' for each commit whose message you want to fix. Save and close.
+# For each chosen commit, Git will open the message: remove the "Made-with: ..." line, save and close.
+# Then force-push your branch (only for your own PR branch):
+$ git push --force-with-lease
+```
 
 ## Final Steps
 
 Before submitting your blog post:
 
 - Ensure all files are added to your repository.
+- For new or migrated posts, confirm that `index.qmd` exists and that
+  `makim pages.build` successfully generates the corresponding `index.md`.
 - Submit a pull request to the main `opensciencelabs.github.io` repository for
   review.
 

_quarto.yml

@@ -0,0 +1,5 @@
+# Project-level Quarto config. Ensures GFM output keeps YAML front matter
+# so blog index.md have title, date, authors, tags, etc. for MkDocs.
+format:
+  gfm:
+    variant: +yaml_metadata_block

bkp/blogs/call-for-interns-2024-01/index.md

@@ -209,8 +209,7 @@ requirements.
   way to define targets and dependencies. Instead of using the Makefile format,
   it uses yaml format.
 - **Categories:** DevOps, Automation
-- **Organization/Project Webpage URL:**
-  [https://osl-incubator.github.io/makim/](https://osl-incubator.github.io/makim/)
+- **Organization/Project Webpage URL:** [https://makim.org/](https://makim.org/)
 - **Contact:** Ivan Ogasawara
   [ivan.ogasawara@gmail.com](mailto:ivan.ogasawara@gmail.com)
 - **Project Ideas URL:**

bkp/opportunities/internship/cycles/2024-01.md

@@ -309,7 +309,7 @@ requirements.
 - **Description**: Makim (or makim) is based on make and focus on improve the
   way to define targets and dependencies. Instead of using the Makefile format,
   it uses yaml format.
-- **Organization/Project Webpage URL**: <https://osl-incubator.github.io/makim/>
+- **Organization/Project Webpage URL**: <https://makim.org/>
 - **Contact**: Ivan Ogasawara (ivan.ogasawara@gmail.com)
 - **Project Ideas URL**: <https://github.com/osl-incubator/makim/issues/74>
 - **Application Record**:

bkp/opportunities/internship/cycles/2024-02.md

@@ -315,7 +315,7 @@ requirements.
 - **Description**: Makim (or makim) is based on make and focus on improve the
   way to define targets and dependencies. Instead of using the Makefile format,
   it uses yaml format.
-- **Organization/Project Webpage URL**: <https://osl-incubator.github.io/makim/>
+- **Organization/Project Webpage URL**: <https://makim.org/>
 - **Contact**: Ivan Ogasawara (ivan.ogasawara@gmail.com)
 - **Project Ideas URL**:
   <https://github.com/osl-incubator/makim/wiki/OSL-Internship-%E2%80%90-2024-%E2%80%90-2nd-Cycle>

conda/dev.yaml

@@ -7,3 +7,4 @@ dependencies:
   - pip
   - poetry
   - nodejs
+  - quarto