@@ -42,15 +42,13 @@ dependencies and activate it.
4242
4343### Creating a New Blog Post
4444
45- 1 . ** Prepare the Blog Post:**
45+ 1 . ** Prepare the Blog Post (Quarto-first workflow) :**
4646
4747 - Navigate to ` pages/blog ` and create a new folder with a slugified version
4848 of your blog post's title. Use
4949 [ https://slugify.online/ ] ( https://slugify.online/ ) to generate a slug.
50- - Inside this folder, create your blog post file:
51- - For Markdown: ` index.md `
52- - For Jupyter Notebooks: ` index.ipynb ` (use Jupyter Lab to create this
53- directly)
50+ - Inside this folder, create your blog post as a ** Quarto document** :
51+ - ` index.qmd `
5452
55532 . ** Include a Header Image:**
5654 - Place a header image (either ` header.png ` or ` header.jpg ` ) in your blog
@@ -70,8 +68,8 @@ dependencies and activate it.
7068
7169### Metadata and Formatting
7270
73- - ** Markdown Posts:** Add a metadata block at the beginning of your ` index.md `
74- file:
71+ - ** Quarto ( ` .qmd ` ) Posts:** Add a metadata block at the beginning of your
72+ ` index.qmd ` file:
7573
7674 ``` markdown
7775 ---
@@ -87,20 +85,54 @@ dependencies and activate it.
8785 ---
8886 ```
8987
90- - ** Jupyter Notebook Posts:** The first cell of your ` index.ipynb ` should be in
91- ` raw ` mode containing the same metadata as above.
88+ The body of the file uses standard Markdown plus any Quarto features you need
89+ (code chunks, figures, etc.). During the build, ` makim pages.build ` will
90+ render ` index.qmd ` to ` index.md ` using Quarto so that MkDocs can consume the
91+ generated Markdown.
9292
93933 . ** Building and Viewing:**
94- - If using a Jupyter Notebook, run ` makim pages.build ` to convert the
95- notebook into a Markdown file (` index.md ` ).
96- - Add the generated ` index.md ` to your repository as it will be used to
97- render the webpage.
94+ - Run ` makim pages.build ` to render ` index.qmd ` to ` index.md ` and build the
95+ site. The generated ` index.md ` is used to render the webpage.
96+
97+ ### Regenerating blog Markdown (for CI)
98+
99+ CI expects the rendered ` index.md ` files under ` pages/blog/*/ ` to be committed.
100+ If you change ` .qmd ` content or metadata, regenerate and push the markdown:
101+
102+ ``` bash
103+ # From repo root with conda env active (e.g. on WSL or Linux)
104+ $ makim pages.pre-build
105+ $ git add pages/blog/* /index.md
106+ $ git commit -m " chore: sync rendered blog index.md from qmd"
107+ $ git push
108+ ```
109+
110+ On Windows, use WSL or a Linux environment so ` makim pages.pre-build ` (Quarto)
111+ runs correctly.
112+
113+ ### Commit messages
114+
115+ Keep commit messages professional and descriptive. Do not add tool or editor
116+ tags (e.g. "Made-with: Cursor") to commit messages.
117+
118+ To fix existing commits that contain such a line (e.g. before pushing a PR):
119+
120+ ``` bash
121+ # Rebase the last N commits (replace 3 with how many need fixing)
122+ $ git rebase -i HEAD~3
123+ # In the editor, change 'pick' to 'reword' for each commit whose message you want to fix. Save and close.
124+ # For each chosen commit, Git will open the message: remove the "Made-with: ..." line, save and close.
125+ # Then force-push your branch (only for your own PR branch):
126+ $ git push --force-with-lease
127+ ```
98128
99129## Final Steps
100130
101131Before submitting your blog post:
102132
103133- Ensure all files are added to your repository.
134+ - For new or migrated posts, confirm that ` index.qmd ` exists and that
135+ ` makim pages.build ` successfully generates the corresponding ` index.md ` .
104136- Submit a pull request to the main ` opensciencelabs.github.io ` repository for
105137 review.
106138
0 commit comments