Import Quarto posts and expand blog sync bridge

2026-06-20 04:01:13 +01:00 · 2026-06-20 04:01:13 +01:00 · e7227844c7
commit e7227844c7
parent 4ddaba7c7d
406 changed files with 7943 additions and 7637 deletions
--- a/CONTENT_BRIDGE.md
+++ b/CONTENT_BRIDGE.md
@ -0,0 +1,166 @@
+# Blog Content Bridge
+
+The public Obsidian vault is the writing source of truth. The Astro sites are
+deployable targets that receive copied Markdown and assets.
+
+## Folder Map
+
+| Vault folder           | Astro content folder                        | Public domain                        |
+| ---------------------- | ------------------------------------------- | ------------------------------------ |
+| `blogs/01-research`    | `sites/research/src/content/research`       | `https://research.neeldhara.blog`    |
+| `blogs/02-vibes`       | `sites/vibes/src/content/vibes`             | `https://vibes.neeldhara.blog`       |
+| `blogs/03-puzzles`     | `sites/puzzles/src/content/puzzles`         | `https://puzzles.neeldhara.blog`     |
+| `blogs/04-reflections` | `sites/reflections/src/content/reflections` | `https://reflections.neeldhara.blog` |
+| `blogs/05-poetry`      | `sites/poetry/src/content/poetry`           | `https://poetry.neeldhara.blog`      |
+| `blogs/06-reviews`     | `sites/reviews/src/content/reviews`         | `https://reviews.neeldhara.blog`     |
+| `blogs/07-art`         | `sites/art/src/content/art`                 | `https://art.neeldhara.blog`         |
+| `blogs/micro`          | `../micro/src/content/blog`                 | `https://micro.neeldhara.blog`       |
+
+The installed Obsidian plugin lives at:
+
+```text
+/Users/neeldhara/obsidian/public/.obsidian/plugins/microblog-sync
+```
+
+The versioned copy lives in this repo at:
+
+```text
+obsidian-plugin/microblog-sync
+```
+
+The plugin id remains `microblog-sync`, but Obsidian shows it as **Blog Family
+Sync**.
+
+## Post Layout
+
+Use one folder per post:
+
+```text
+blogs/01-research/example-post/index.md
+blogs/01-research/example-post/diagram.png
+```
+
+The folder path becomes the public URL:
+
+```text
+blogs/01-research/example-post/index.md
+https://research.neeldhara.blog/example-post/
+```
+
+Nested folders are supported:
+
+```text
+blogs/04-reflections/exportober/2021/index.md
+https://reflections.neeldhara.blog/exportober/2021/
+```
+
+## Frontmatter
+
+Every public post needs the fields required by the Astro content schema:
+
+```yaml
+---
+title: "Post title"
+description: "One or two sentence summary for cards and RSS."
+pubDate: "2024-05-10"
+authorName: "Neeldhara"
+---
+```
+
+Optional fields currently understood by the sites include `updatedDate`,
+`image`, and `authorImage`. Prefer colocated images in the body over remote
+stock images.
+
+The Quarto import also preserved `sourceCategories` and `sourcePath`. Astro
+strips unknown schema fields, but they are useful in Obsidian for provenance.
+
+## Markdown Conventions
+
+Standard Markdown headings, lists, links, tables, code fences, footnotes, and
+raw HTML are preserved.
+
+Use colocated relative assets:
+
+```markdown
+![Caption](image.png)
+```
+
+Quarto image attributes such as `{width=70%}` were removed during import. Going
+forward, use normal Markdown and let Astro CSS handle presentation.
+
+Quarto callouts were converted to portable blockquotes:
+
+```markdown
+> **Note**
+>
+> Text of the callout.
+```
+
+Use the same convention for new notes:
+
+```markdown
+> **Warning**
+>
+> This point needs attention.
+```
+
+Quarto margin notes such as `[text]{.aside}` were converted to:
+
+```markdown
+> **Aside:** text
+```
+
+## Import Rules
+
+The import script is:
+
+```text
+scripts/import-quarto-blog.mjs
+```
+
+It reads the Quarto archive, skips `draft: true`, converts `index.qmd` to
+`index.md`, copies colocated assets, and writes a temporary tree under
+`/private/tmp/quarto-blog-import`.
+
+The first import made these category choices:
+
+| Blog          | Rule of thumb                                                      |
+| ------------- | ------------------------------------------------------------------ |
+| `research`    | CS/math exposition, lecture notes, and academic explainers.        |
+| `vibes`       | LLM-assisted making, interactives, and generated-tool experiments. |
+| `puzzles`     | Puzzle/game/problem posts.                                         |
+| `reflections` | Essays, speeches, teaching/career notes, and Exportober context.   |
+| `poetry`      | Poems.                                                             |
+| `reviews`     | Tool, workflow, software, website, book-list, and tutorial posts.  |
+| `art`         | Visual/sketchnote/design/communications-oriented posts.            |
+
+See `IMPORT_REPORT.md` for the specific source-to-destination mapping.
+
+## Sync Rules
+
+- Obsidian is the source of truth for day-to-day writing.
+- Auto-sync copies changes from the matching `blogs/...` folder into the
+  matching local Astro content folder.
+- The plugin includes Markdown plus common web assets: images, PDFs,
+  JSON/YAML, JS, CSS, HTML, and text files.
+- One-way sync does not delete target files unless **Delete orphaned target
+  files** is enabled.
+- The initial Quarto import used replace-style sync to clear placeholder Astro
+  posts. Day-to-day editing should use the plugin.
+
+## Preview And Publish
+
+Use these Obsidian commands:
+
+- `Blog Family Sync: Sync and preview current note`
+- `Blog Family Sync: Publish current note`
+- `Blog Family Sync: Publish all changes for current blog`
+
+Preview detects the current note's folder, starts the matching Astro dev server
+on its configured local port, and opens the post URL.
+
+Publish does three things:
+
+1. Sync vault content into the local repo.
+2. Run the configured Astro build command.
+3. Commit and push to Forgejo, where Dokploy picks up the change.