170 lines
5.5 KiB
Markdown
170 lines
5.5 KiB
Markdown
# 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.
|
|
|
|
Use `main-feature: true` on at most one post per blog to pin a fixed featured
|
|
post on the `neeldhara.blog` homepage. The homepage still shows the two newest
|
|
non-featured posts for that blog, sorted by `pubDate`.
|
|
|
|
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
|
|
|
|
```
|
|
|
|
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.
|