Pages CMS for My Astro Blog and Quartz Notes

Update (2025): This walkthrough anchors the Astro Erudite series. The .pages.yml shown below follows the native Erudite post-folder structure.

1. Get the repos ready

I keep two git projects side by side: astro-blog for the main site and private-quartz for the evergreen notes. Pages CMS reads files straight from the repository, so all I need locally is the repo on disk and a .pages.yml file in the root. I commit the config once and let Pages CMS generate commits when I publish content.

2. Configure media buckets for the Astro blog

Pages CMS needs to know where to drop uploads. In the Astro project I keep two buckets: uploads for post screenshots and site-assets for icons, downloads, and anything that might be reused. Both point back into public/ so Astro can serve files without extra glue, and the config now mirrors the language that Pages CMS uses in its docs.

1
media:
2
  - name: uploads
3
    label: Post assets
4
    input: public/images/uploads
5
    output: /images/uploads
6
    categories: [image, document]
7
  - name: site-assets
8
    label: Site assets
9
    input: public/assets
10
    output: /assets
11
    categories: [image, code, document]

The input value tells Pages CMS which folder in the repo should hold the raw file. The output value is the public URL that the Markdown editor will insert. With this mapping, uploads land in public/images/uploads and resolve as /images/uploads/example.png, which lines up with how the docs recommend handling media.

3. Map the Astro collection with post folders

My blog posts live inside src/content/blog using the native Astro Erudite layout: each top-level post has its own folder and an index.md file. A child post can sit beside that file inside the same folder, which lets Erudite treat it as a subpost.

1
content:
2
  - name: blog
3
    label: Blog Posts
4
    type: collection
5
    path: src/content/blog
6
    filename: '{{fields.slug}}/index.md'
7
    subfolders: true
8
    view:
9
      layout: tree
10
      primary: title
11
      fields: [title, date, tags, draft]
12
      sort: ['date desc', 'title asc']

The saved path now matches Erudite’s expected routing directly: src/content/blog/my-post/index.md becomes /blog/my-post/. Subposts live one level deeper in the same parent folder and can use order when a series needs manual sequencing.

4. Mirror the Astro front matter schema

The active schema is intentionally small. Each post needs only the fields that Erudite reads at build time.

1
fields:
2
  - name: title
3
    label: Title
4
    type: string
5
    required: true
6
  - name: description
7
    label: Description
8
    type: text
9
    required: true
10
  - name: date
11
    label: Publish date & time
12
    type: date
13
    options: { time: true, format: "yyyy-MM-dd'T'HH:mm:ss'Z'" }
14
    required: true
15
  - name: authors
16
    label: Authors
17
    type: select
18
    options:
19
      multiple: true
20
      values:
21
        - { label: 'Dzaki Azhari', value: 'dzaki-azhari' }
22
  - name: tags
23
    label: Tags
24
    type: select
25
    options:
26
      multiple: true
27
      creatable: true
28
  - name: draft
29
    label: Draft
30
    type: boolean
31
  - name: image
32
    label: Featured image
33
    type: image
34
  - name: order
35
    label: Subpost order
36
    type: number
37
  - name: body
38
    label: Body
39
    type: markdown

Fields from the older setup are no longer part of the active post front matter.

5. Full Config Examples

Below are the complete .pages.yml configurations for both Astro and Quartz projects for reference.

5.1 Astro

1
# .pages.yml
2

3
media:
4
  - name: uploads
5
    label: Uploads
6
    input: public/images/uploads
7
    output: /images/uploads
8
    categories: [image, document]
9

10
content:
11
  - name: blog
12
    label: Blog Posts
13
    type: collection
14
    path: src/content/blog
15
    filename: '{{fields.slug}}/index.md'
16
    subfolders: true
17
    view:
18
      layout: tree
19
      primary: title
20
      fields: [title, date, tags, draft]
21
      sort: ['date desc', 'title asc']
22
      search: [title, description, tags]
23
    fields:
24
      - name: slug
25
        label: Slug
26
        type: string
27
        required: true
28
        pattern:
29
          regex: '^[a-z0-9]+(?:-[a-z0-9]+)*$'
30
          message: 'Use lowercase words separated by hyphens.'
31
      - name: title
32
        label: Title
33
        type: string
34
        required: true
35
      - name: description
36
        label: Description
37
        type: text
38
        required: true
39
      - name: date
40
        label: Publish date & time
41
        type: date
42
        options: { time: true, format: "yyyy-MM-dd'T'HH:mm:ss'Z'" }
43
        required: true
44
      - name: authors
45
        label: Authors
46
        type: select
47
        options:
48
          multiple: true
49
          values:
50
            - { label: 'Dzaki Azhari', value: 'dzaki-azhari' }
51
      - name: draft
52
        label: Draft
53
        type: boolean
54
      - name: tags
55
        label: Tags
56
        type: select
57
        options:
58
          multiple: true
59
          creatable: true
60
          values:
61
            - { label: 'dev', value: 'dev' }
62
            - { label: 'blog', value: 'blog' }
63
            - { label: 'others', value: 'others' }
64
      - name: image
65
        label: Featured image
66
        type: image
67
        required: false
68
      - name: order
69
        label: Subpost order
70
        type: number
71
        required: false
72
      - name: body
73
        label: Body
74
        type: markdown

5.2 Quartz

1
# Pages CMS configuration for this Quartz site
2

3
# Where media files are stored and how they resolve in the built site
4
# Using the content folder keeps images co-located with notes.
5
media:
6
  - name: content
7
    label: Content Media
8
    input: content
9
    output: /
10

11
# Shared field definitions for garden notes. Update descriptions when adding new metadata.
12
content:
13
  # Home page (single file)
14
  - name: home
15
    label: Home Page
16
    type: file
17
    path: content/index.md
18
    fields: &page_fields
19
      - name: title
20
        label: Title
21
        type: string
22
        description: 'Primary heading shown in Quartz. Begin with the Johnny.Decimal code (e.g. 21.03 Symbol and Punctuation).'
23
      - name: description
24
        label: Description
25
        type: text
26
        description: 'One or two sentences to surface in search previews and link unfurls.'
27
      - name: tags
28
        label: Tags
29
        type: string
30
        list: true
31
        description: 'Topics that power Quartz search, the graph view, and Pages CMS filters. Press Enter after each tag.'
32
      - name: cssclasses
33
        label: CSS classes
34
        type: string
35
        list: true
36
        description: 'Optional Quartz class names (e.g. cards) for bespoke styling hooks.'
37
      - name: aliases
38
        label: Aliases
39
        type: string
40
        list: true
41
        description: 'Alternate names or translations so Quartz resolves wikilinks correctly.'
42
      - name: draft
43
        label: Draft
44
        type: boolean
45
        default: false
46
        description: 'Leave enabled while notes are in progress. Quartz hides drafted notes from publish and RSS feeds.'
47
      - name: permalink
48
        label: Permalink
49
        type: string
50
        description: 'Optional slug override for Quartz permalinks (e.g. index, meta, disclaimer).'
51
      - name: enableToc
52
        label: Show table of contents
53
        type: boolean
54
        description: 'Disable when a page should hide the Quartz table of contents.'
55
      - name: password
56
        label: Password
57
        type: string
58
        description: 'Optional staticryption password. Leave blank unless you intend to protect the note.'
59
      - name: created
60
        label: Created
61
        type: date
62
        description: 'Original creation timestamp in Japan Standard Time (UTC+09:00).'
63
        options: &timestamp_options
64
          time: true
65
          step: 1
66
          format: "yyyy-MM-dd'T'HH:mm:ss'+09:00'"
67
      - name: updated
68
        label: Updated
69
        type: date
70
        description: 'Last updated timestamp in Japan Standard Time (UTC+09:00).'
71
        options: *timestamp_options
72
      - name: body
73
        label: Body
74
        type: markdown
75
        description: 'Markdown content of the note. Match the heading with the Johnny.Decimal title for consistency.'
76
        ui:
77
          format: github
78

79
  # Folder-based collections
80
  - name: home-notes
81
    label: Home Notes
82
    description: 'Johnny.Decimal 01–09: Home base, Meta docs, and Inbox processing.'
83
    type: collection
84
    path: content/Home
85
    match: '**/*.md'
86
    filename: '{primary}.md'
87
    subfolders: true
88
    view: &collection_view
89
      layout: tree
90
      primary: title
91
      fields: [title, tags, updated, draft]
92
      sort: ['title']
93
      search: [title, tags]
94
    fields: *page_fields
95

96
  - name: language-lab
97
    label: Language Lab
98
    description: 'Johnny.Decimal 21–29: language study notes, practice logs, and references.'
99
    type: collection
100
    path: content/Language Lab
101
    match: '**/*.md'
102
    filename: '{primary}.md'
103
    subfolders: true
104
    view: *collection_view
105
    fields: *page_fields
106

107
  - name: finbiz-hub
108
    label: Finbiz Hub
109
    description: 'Johnny.Decimal 31–39: business intelligence decks, market analysis, and storyboards.'
110
    type: collection
111
    path: content/Finbiz Hub
112
    match: '**/*.md'
113
    filename: '{primary}.md'
114
    subfolders: true
115
    view: *collection_view
116
    fields: *page_fields
117

118
  - name: living-chronicles
119
    label: Living Chronicles
120
    description: 'Johnny.Decimal 41–49: personal chronicle entries and relocation journals.'
121
    type: collection
122
    path: content/Living Chronicles
123
    match: '**/*.md'
124
    filename: '{primary}.md'
125
    subfolders: true
126
    view: *collection_view
127
    fields: *page_fields
128

129
  - name: references
130
    label: References
131
    description: 'Johnny.Decimal 51–59: media logs, songs, and bibliographies.'
132
    type: collection
133
    path: content/References
134
    match: '**/*.md'
135
    filename: '{primary}.md'
136
    subfolders: true
137
    view: *collection_view
138
    fields: *page_fields
139

140
# Settings (optional): hide the Settings page in the CMS for simplicity
141
settings:
142
  hide: false

6. Configure Quartz media and layout

My Quartz project keeps note assets inside static/uploads, so the Pages CMS config defines a single media bucket tied to that folder. Because Quartz publishes the static directory, the CMS output path is /uploads. The collection now relies on a single tree view anchored by the reusable &page_fields block, so every Johnny.Decimal folder inherits the same metadata requirements without duplication.

The updated field definitions also switch to the type: list syntax that Pages CMS recommends and mark the most important fields (title, publish, draft) as required or defaulted, which makes the editor guard against accidental public pushes.

7. Mirror Quartz front matter

Quartz relies on a handful of boolean switches that control publishing, sharing, and note status. I expose them as checkboxes so the CMS writes valid YAML every time. I also keep tags and aliases as list inputs because Quartz uses them for backlinks and display names.

When I flip publish to true, the Quartz deployment workflow picks up the note during the next sync. Leaving draft true keeps the note local even if publish was ticked accidentally.

8. Connect the repos to Pages CMS

Once both .pages.yml files are committed, I open the Pages CMS dashboard and add each repository. The flow is the same for both projects:

Authorize GitHub and select the repository.
Choose the branch (I stick with main).
Confirm the Pages CMS sees the collection. The Astro repo shows the post tree, while the Quartz repo shows the note folders.
Test a dry run by creating a draft entry, filling the required fields, and saving. Pages CMS opens a pull request containing the new Markdown file.

After that, I can write from anywhere. The CMS fills the front matter for me, keeps uploads in the right folders, and never breaks the schema that the projects rely on.