# 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.