Pages CMS for My Astro Blog and Quartz Notes

Update (2025): This walkthrough anchors the Astro Erudite series. The .pages.yml shown below is the active configuration, including the new parentSlug field for nesting subposts under this parent article.

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 field templating

My blog posts live inside src/content/blog, grouped by year folders. The CMS collection reflects that layout and now uses the {{fields.*}} templating so Pages CMS builds paths straight from whatever I type into the form. I also expanded the exclude list to hide _drafts folders whether they’re files or directories.

1
content:
2
  - name: blog
3
    label: Blog Posts
4
    description: 'Long-form stories that surface on dzakiazhari.com. Paths and metadata map directly to src/content.config.ts.'
5
    type: collection
6
    path: src/content/blog
7
    filename: '{{fields.year}}/{{#fields.parentSlug}}{{fields.parentSlug}}/{{/fields.parentSlug}}{{fields.slug}}.md'
8
    exclude:
9
      - '**/_*/**'
10
      - '**/_*'
11
    subfolders: true
12

13
    view:
14
      layout: tree
15
      primary: title
16
      fields: [title, pubDatetime, tags, draft]
17
      sort: ['pubDatetime desc', 'title asc']
18
      search: [title, description, tags]
19
      default:
20
        sort: pubDatetime
21
        order: desc

The tree view highlights the draft state so I can spot unpublished work instantly. Using {{fields.year}}, the optional parentSlug block, and {{fields.slug}} keeps the saved path aligned with src/lib/data-utils.ts without relying on implicit collection values.

4. Mirror the Astro front matter schema

Every field in the CMS corresponds to a field in src/content.config.ts. After re-reading the Pages CMS guides I grouped inputs by intent, added helper descriptions, and tightened validation so the editor blocks malformed front matter before it hits git.

Path controls for the year, optional parent slug, and final slug (select + regex pattern).
Required metadata with labels, length hints, and required: true flags.
Optional overrides for drafts, canonical links, OG uploads, timezone, and subpost ordering.

Here’s a representative slice of the field block:

1
fields:
2
  - name: year
3
    label: Year folder
4
    type: select
5
    description: "Creates the folder segment under src/content/blog/{year}."
6
    default: "2025"
7
    options:
8
      placeholder: "Choose a year"
9
      creatable: true
10
      values:
11
        - { label: "2023", value: "2023" }
12
        - { label: "2024", value: "2024" }
13
        - { label: "2025", value: "2025" }
14
  - name: slug
15
    label: Slug (filename)
16
    type: string
17
    description: "Lowercase with hyphens only. The CMS writes {slug}.md under the chosen year."
18
    required: true
19
    pattern:
20
      regex: "^[a-z0-9]+(?:-[a-z0-9]+)*$"
21
      message: "Use lowercase words separated by hyphens without the .md extension."
22
  - name: parentSlug
23
    label: Parent slug (optional)
24
    type: string
25
    description: "Only fill when nesting subposts. Match the parent folder slug (e.g. parent-post)."
26
    pattern:
27
      regex: "^[a-z0-9]+(?:-[a-z0-9]+)*$"
28
      message: "Leave blank for top-level posts; otherwise mirror the parent slug."
29
  - name: title
30
    label: Title
31
    type: string
32
    description: "Displayed as the page <h1> and the document title tag."
33
    required: true
34
  - name: description
35
    label: Description
36
    type: text
37
    description: "Short summary for cards, RSS, and SEO meta tags."
38
    required: true
39
    options:
40
      maxlength: 180
41
  - name: pubDatetime
42
    label: Publish date & time
43
    type: date
44
    options: { time: true, format: "yyyy-MM-dd'T'HH:mm:ss'Z'" }
45
    description: "Posts stay hidden until this timestamp (with a 15-minute grace window)."
46
    required: true
47
  - name: modDatetime
48
    label: Last modified
49
    type: date
50
    options: { time: true, format: "yyyy-MM-dd'T'HH:mm:ss'Z'" }
51
    description: "Optional edit timestamp for changelog banners and structured data."
52
  - name: draft
53
    label: Draft
54
    type: boolean
55
    description: "Enable to keep the entry out of listings, RSS, and builds."
56
  - name: tags
57
    label: Tags
58
    type: select
59
    default: ["others"]
60
    options:
61
      multiple: true
62
      creatable: true
63
      placeholder: "Add topics like dev, blog, garden"
64
  - name: order
65
    label: Subpost order
66
    type: number
67
    description: "Optional integer to keep multi-part posts in a deliberate sequence."
68
  - name: ogImage
69
    label: OG image
70
    type: image
71
    options:
72
      media: uploads
73
  - name: canonicalURL
74
    label: Canonical URL
75
    type: string
76
    pattern:
77
      regex: "^(https?:\\/\\/)([^\s]+)$"
78
  - name: timezone
79
    label: Timezone
80
    type: string
81
    default: "Asia/Tokyo"
82
    description: "Needed only when writing outside the default site timezone."

The updated schema keeps Pages CMS aligned with the Astro Zod rules while leaning on the nicer UI touches from the documentation. Placeholders, regex messages, and media bucket defaults all kick in at the right moments, and so far I haven’t hit a validation error after the refresh.

Full Config Examples

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

Astro

1
# .pages.yml
2

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

15
content:
16
  - name: blog
17
    label: Blog Posts
18
    description: "Long-form stories that surface on dzakiazhari.com. Paths and metadata map directly to src/content.config.ts."
19
    type: collection
20
    # Keep this path aligned with the Astro content collection defined in src/content.config.ts
21
    path: src/content/blog
22
    # Blog posts live in year-based folders; the optional parentSlug nests subposts beneath the parent directory.
23
    # Pages CMS uses moustache-style templating so the parent segment only renders when provided.
24
    filename: "{{fields.year}}/{{#fields.parentSlug}}{{fields.parentSlug}}/{{/fields.parentSlug}}{{fields.slug}}.md"
25
    exclude:
26
      - "**/_*/**"
27
      - "**/_*"
28
    subfolders: true
29

30
    view:
31
      layout: tree
32
      primary: title
33
      # Show the post title in the list, with date and tags alongside
34
      fields: [ title, pubDatetime, tags, draft ]
35
      sort: [ "pubDatetime desc", "title asc" ]
36
      search: [ title, description, tags ]
37
      default:
38
        sort: pubDatetime
39
        order: desc
40

41
    fields:
42
      # --- path controls ---
43
      - name: year
44
        label: Year folder
45
        type: select
46
        description: "Creates the folder segment under src/content/blog/{year}."
47
        default: "2025"
48
        options:
49
          placeholder: "Choose a year"
50
          creatable: true
51
          values:
52
            - { label: "2023", value: "2023" }
53
            - { label: "2024", value: "2024" }
54
            - { label: "2025", value: "2025" }
55
            - { label: "2026", value: "2026" }
56
            - { label: "2027", value: "2027" }
57
            - { label: "2028", value: "2028" }
58
            - { label: "2029", value: "2029" }
59
            - { label: "2030", value: "2030" }
60

61
      - name: slug
62
        label: Slug (filename)
63
        type: string
64
        description: "Lowercase with hyphens only. The CMS writes {slug}.md under the chosen year."
65
        required: true
66
        pattern:
67
          regex: "^[a-z0-9]+(?:-[a-z0-9]+)*$"
68
          message: "Use lowercase words separated by hyphens without the .md extension."
69

70
      - name: parentSlug
71
        label: Parent slug (optional)
72
        type: string
73
        required: false
74
        description: "Fill only when this entry is a subpost. Match the parent folder slug (e.g. parent-post)."
75
        pattern:
76
          regex: "^[a-z0-9]+(?:-[a-z0-9]+)*$"
77
          message: "Leave blank for top-level posts; otherwise mirror the parent slug."
78

79
      # --- frontmatter (matches Astro schema) ---
80
      - name: title
81
        label: Title
82
        type: string
83
        description: "Displayed as the page <h1> and the document title tag."
84
        required: true
85

86
      - name: description
87
        label: Description
88
        type: text
89
        description: "Short summary for cards, RSS, and SEO meta tags."
90
        required: true
91
        options:
92
          maxlength: 180
93

94
      - name: pubDatetime
95
        label: Publish date & time
96
        type: date
97
        options: { time: true, format: "yyyy-MM-dd'T'HH:mm:ss'Z'" }
98
        description: "Posts remain hidden until this timestamp (with a 15-minute grace window)."
99
        required: true
100

101
      - name: modDatetime
102
        label: Last modified
103
        type: date
104
        options: { time: true, format: "yyyy-MM-dd'T'HH:mm:ss'Z'" }
105
        required: false
106
        description: "Optional edit timestamp for changelog banners and structured data."
107

108
      - name: draft
109
        label: Draft
110
        type: boolean
111
        description: "Toggle on to keep the post hidden from listings, RSS, and builds."
112

113
      - name: tags
114
        label: Tags
115
        type: select
116
        default: [ "others" ]
117
        options:
118
          multiple: true
119
          creatable: true
120
          placeholder: "Add topics like dev, blog, garden"
121
          values:
122
            - { label: "dev", value: "dev" }
123
            - { label: "blog", value: "blog" }
124
            - { label: "garden", value: "garden" }
125
            - { label: "life", value: "life" }
126
            - { label: "productivity", value: "productivity" }
127
            - { label: "notes", value: "notes" }
128
            - { label: "others", value: "others" }
129
        description: "Multi-select tags surface related content chips and search facets."
130

131
      - name: order
132
        label: Subpost order
133
        type: number
134
        required: false
135
        description: "Optional integer to sort multi-part subposts after publish date."
136

137
      # optionals
138
      - name: ogImage
139
        label: OG image
140
        type: image
141
        required: false
142
        description: "Uploads to /public/images/uploads. Leave blank to auto-generate dynamic OG art."
143
        options:
144
          media: uploads
145

146
      - name: canonicalURL
147
        label: Canonical URL
148
        type: string
149
        required: false
150
        description: "Use for cross-posts hosted elsewhere."
151
        pattern:
152
          regex: "^(https?:\\/\\/)([^\s]+)$"
153
          message: "Use an absolute URL starting with http:// or https://"
154

155
      - name: timezone
156
        label: Timezone
157
        type: string
158
        default: "Asia/Tokyo"
159
        description: "Overrides the global SITE.timezone for posts written elsewhere."
160

161
      # body
162
      - name: body
163
        label: Body
164
        type: markdown
165
        description: 'Write in Markdown. Supports callouts, code fences with file="" metadata, and remark-collapse toggles.'

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

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

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

7. 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 yearly archive 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.