Skip to content

Commit 5d964a3

Browse files
delucisdelucis
committed
Restructure repo
1 parent e246b81 commit 5d964a3

37 files changed

+262
-251
lines changed

‎.npmignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
demo

‎README.md

Lines changed: 70 additions & 121 deletions
Original file line numberDiff line numberDiff line change
@@ -1,146 +1,95 @@
1-
# Astro Blog with Netlify CMS
1+
![Astro + Netlify CMS](header.png)
22

3-
This example is based on [the basic Astro blog starter kit][starter].
3+
<p align="center">
4+
Add Netlify CMS’s admin dashboard to any Astro project.
5+
</p>
46

5-
It adds:
7+
## Installation
68

7-
- [Netlify CMS][cms] dashboard at `/admin`
8-
- Live preview of posts in Netlify CMS
9-
- [Local proxy server][proxy] to allow local content updates via the CMS
10-
- Netlify Identity for authenticating with the admin app
11-
12-
## Quick deploy
13-
14-
[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)][deploy]
15-
16-
☝️ Click this button to copy this project to your own GitHub (or GitLab)
17-
account and set up continuous deployment with Netlify as if by magic. ✨
18-
19-
Once you’ve got the project set up, you do need to
20-
[activate Netlify Identity in the Netlify UI][identity] and then enable
21-
[“Git Gateway”][gateway] to allow e-mail/password authentication.
22-
23-
## Commands
24-
25-
All commands are run from the root of the project, from a terminal:
26-
27-
| Command | Action |
28-
| :---------------- | :------------------------------------------------- |
29-
| `npm install` | Installs dependencies |
30-
| `npm run dev` | Starts local dev & Netlify CMS proxy servers |
31-
| `npm run build` | Build your production site to `./dist/` |
32-
| `npm run preview` | Serve `./dist/` & run the Netlify CMS proxy server |
33-
34-
## Considerations
35-
36-
Netlify CMS is a single-page React app. It supports a live preview pane while
37-
editing posts, but previews must also be React components. This means any
38-
layouts/components that you want to preview in the CMS must be written using
39-
React.
40-
41-
We can also get reasonably good preview support for components in Markdown, but
42-
the same caveat applies: they’ve got to be React components. This project
43-
[registers them as custom editor components][editor-components].
44-
45-
Astro makes it fairly simple to share our components across the site and in the
46-
editor previews, but it does mean we opt out of some Astro benefits like
47-
auto-scoped styles and are forced to use React (at least for things that need
48-
previewing — this project still uses Astro components for other things).
49-
50-
### Blockers
51-
52-
- Expressions in Markdown, like `{frontmatter.value}` are not supported in live
53-
previews. Two blockers from Netlify CMS:
54-
55-
1. [No support for custom _inline_ preview components][cms5065] (so
56-
expressions could work at a block-level, but not in the middle of text).
57-
58-
2. Editor components can’t access other post data, so it’s not possible to
59-
provide variables like `frontmatter` to expressions. (More obviously,
60-
APIs like `Astro.request` aren’t available in the browser.)
9+
```bash
10+
npm i astro-netlify-cms
11+
```
6112

62-
- Component support in Markdown requires that components are imported in the
63-
front matter’s `setup` block. This repository suggests an architecture for
64-
providing components to the editor and sets a default `setup` block that
65-
imports all currently known components. [A bug][astro2474] in Astro means we
66-
can’t (currently) manage with a single `import Components` and then render
67-
`<Component.Button>` or `<Component.Whatever>`, but if that is fixed, this
68-
step can be more robust.
13+
## Usage
6914

70-
## Project Structure
15+
### Experimental status
7116

72-
Inside of your Astro project, you'll see the following folders and files:
17+
Third-party integrations are currently only supported behind a flag, so you’ll
18+
need to update your Astro scripts to include the flag:
7319

74-
```
75-
/
76-
├── public/
77-
│ └── ...
78-
├── src/
79-
│ ├── collections/ # CMS collection configurations
80-
│ │ └── posts/
81-
│ ├── components/
82-
│ │ ├── index.ts # Export custom CMS editor components
83-
│ │ └── ...
84-
│ ├── layouts/
85-
│ ├── pages/
86-
│ │ ├── admin/ # Page for the Netlify CMS admin dashboard
87-
│ │ ├── posts/
88-
│ │ └── ...
89-
│ ├── scripts/
90-
│ │ └── cms.ts # Script that configures the CMS admin dashboard
91-
│ └── styles/
92-
└── package.json
20+
```bash
21+
astro dev --experimental-integrations
22+
astro build --experimental-integrations
23+
astro preview --experimental-integrations
9324
```
9425

95-
This follows the same logic as a standard Astro project. The additional details
96-
are:
26+
### Adding the integration
27+
28+
To add Netlify CMS to your project, import and use the integration in your
29+
Astro config file, adding it to the `integrations` array.
30+
31+
```js
32+
// astro.config.mjs
33+
34+
import { defineConfig } from 'astro/config';
35+
import NetlifyCMS from 'astro-netlify-cms';
36+
37+
export default defineConfig({
38+
integrations: [
39+
NetlifyCMS({
40+
config: {
41+
backend: {
42+
name: 'git-gateway',
43+
branch: 'main',
44+
},
45+
collections: [
46+
// Content collections
47+
],
48+
},
49+
}),
50+
],
51+
});
52+
```
9753

98-
- `src/collections` — This directory exports an array of collection
99-
configurations for use by the CMS. Each collection object contains the
100-
component used to render a collection item, its CSS, and a configuration
101-
object for Netlify CMS, telling it which fields it needs to edit it.
54+
### Configuration options
10255

103-
- `src/components/index.ts` — This file similarly exposes components that can
104-
be included in Markdown files. That means they also include configuration
105-
for what kind of inputs they need.
56+
You can pass an options object to the integration to configure how it behaves.
10657

107-
- `src/pages/admin/index.astro` — This page serves the admin dashboard for
108-
Netlify CMS.
58+
#### `adminPath`
10959

110-
- `src/scripts/cms.ts` — This script is imported by the `/admin` page and
111-
configures the CMS dynamically based on the components and collections
112-
above.
60+
**Type:** `string`
61+
**Default:** `'/admin'`
11362

114-
### Adding a new collection
63+
Determines the route where the Netlify CMS admin dashboard will be available on your site.
11564

116-
_See `src/collections/posts/index.tsx` for an example._
65+
Feeling nostalgic for WordPress? You could set this to `'/wp-admin'`!
11766

118-
1. Create a directory with the name of your collection under `src/collections`.
67+
#### `config`
11968

120-
2. Write a component to render an item in the collection.
69+
**Type:** `CmsConfig`
12170

122-
3. Export the component, its CSS (if any), and a collection object configuring
123-
it for Netlify CMS.
71+
This option is **required**. It allows you to configure Netlify CMS with the
72+
same options you would use when using Netlify CMS’s `config.yml` file format.
12473

125-
4. Add your collection to the export in `src/collections/index.ts`.
74+
You can see [a full list of configuration options in the Netlify CMS docs](https://www.netlifycms.org/docs/configuration-options/).
12675

127-
### Adding a new editor component
76+
At a minimum, you _must_ set the `backend` and `collections` options.
12877

129-
_See `src/components/Author.tsx` for an example._
78+
#### `previewStyles`
13079

131-
1. Create a component.
80+
**Type:** `Array<string | [string, { raw: true }]>`
13281

133-
2. Write a configuration object detailing the component’s inputs.
82+
Sets custom CSS styles to apply in the Netlify CMS preview pane.
13483

135-
3. Add it to the `Components` and `CMSComponents` exports in
136-
`src/components/index.ts`.
84+
You can provide URLs to external CSS stylesheets (Google Fonts for example), paths to local CSS files in your project, or even raw CSS strings:
13785

138-
[starter]: https://astro.new/blog?on=github
139-
[cms]: https://www.netlifycms.org/
140-
[proxy]: https://www.netlifycms.org/docs/beta-features/#working-with-a-local-git-repository
141-
[deploy]: https://app.netlify.com/start/deploy?repository=https://github.com/delucis/astro-netlify-cms
142-
[identity]: https://docs.netlify.com/visitor-access/identity/
143-
[gateway]: https://docs.netlify.com/visitor-access/git-gateway/
144-
[editor-components]: https://www.netlifycms.org/docs/custom-widgets/#registereditorcomponent
145-
[cms5065]: https://github.com/netlify/netlify-cms/issues/5065
146-
[astro2474]: https://github.com/withastro/astro/issues/2474
86+
```js
87+
previewStyles: [
88+
// Path to a local CSS file, relative to your project’s root directory
89+
'src/styles/main.css',
90+
// A URL to an externally hosted CSS file
91+
'https://fonts.googleapis.com/css2?family=IBM+Plex+Mono&display=swap',
92+
// Raw CSS!
93+
['p { color: red; }', { raw: true }],
94+
];
95+
```

‎demo/README.md

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# Astro Blog with Netlify CMS
2+
3+
This example is based on [the basic Astro blog starter kit][starter].
4+
5+
It adds:
6+
7+
- [Netlify CMS][cms] dashboard at `/admin`
8+
- Live preview of posts in Netlify CMS
9+
- [Local proxy server][proxy] to allow local content updates via the CMS
10+
- Netlify Identity for authenticating with the admin app
11+
12+
## Quick deploy
13+
14+
[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)][deploy]
15+
16+
☝️ Click this button to copy this project to your own GitHub (or GitLab)
17+
account and set up continuous deployment with Netlify as if by magic. ✨
18+
19+
Once you’ve got the project set up, you do need to
20+
[activate Netlify Identity in the Netlify UI][identity] and then enable
21+
[“Git Gateway”][gateway] to allow e-mail/password authentication.
22+
23+
## Commands
24+
25+
All commands are run from the root of the project, from a terminal:
26+
27+
| Command | Action |
28+
| :---------------- | :------------------------------------------------- |
29+
| `npm install` | Installs dependencies |
30+
| `npm run dev` | Starts local dev & Netlify CMS proxy servers |
31+
| `npm run build` | Build your production site to `./dist/` |
32+
| `npm run preview` | Serve `./dist/` & run the Netlify CMS proxy server |
33+
34+
## Considerations
35+
36+
Netlify CMS is a single-page React app. It supports a live preview pane while
37+
editing posts, but previews must also be React components. This means any
38+
layouts/components that you want to preview in the CMS must be written using
39+
React.
40+
41+
We can also get reasonably good preview support for components in Markdown, but
42+
the same caveat applies: they’ve got to be React components. This project
43+
[registers them as custom editor components][editor-components].
44+
45+
Astro makes it fairly simple to share our components across the site and in the
46+
editor previews, but it does mean we opt out of some Astro benefits like
47+
auto-scoped styles and are forced to use React (at least for things that need
48+
previewing — this project still uses Astro components for other things).
49+
50+
### Blockers
51+
52+
- Expressions in Markdown, like `{frontmatter.value}` are not supported in live
53+
previews. Two blockers from Netlify CMS:
54+
55+
1. [No support for custom _inline_ preview components][cms5065] (so
56+
expressions could work at a block-level, but not in the middle of text).
57+
58+
2. Editor components can’t access other post data, so it’s not possible to
59+
provide variables like `frontmatter` to expressions. (More obviously,
60+
APIs like `Astro.request` aren’t available in the browser.)
61+
62+
- Component support in Markdown requires that components are imported in the
63+
front matter’s `setup` block. This repository suggests an architecture for
64+
providing components to the editor and sets a default `setup` block that
65+
imports all currently known components. [A bug][astro2474] in Astro means we
66+
can’t (currently) manage with a single `import Components` and then render
67+
`<Component.Button>` or `<Component.Whatever>`, but if that is fixed, this
68+
step can be more robust.
69+
70+
## Project Structure
71+
72+
Inside of your Astro project, you'll see the following folders and files:
73+
74+
```
75+
/
76+
├── public/
77+
│ └── ...
78+
├── src/
79+
│ ├── collections/ # CMS collection configurations
80+
│ │ └── posts/
81+
│ ├── components/
82+
│ │ ├── index.ts # Export custom CMS editor components
83+
│ │ └── ...
84+
│ ├── layouts/
85+
│ ├── pages/
86+
│ │ ├── admin/ # Page for the Netlify CMS admin dashboard
87+
│ │ ├── posts/
88+
│ │ └── ...
89+
│ ├── scripts/
90+
│ │ └── cms.ts # Script that configures the CMS admin dashboard
91+
│ └── styles/
92+
└── package.json
93+
```
94+
95+
This follows the same logic as a standard Astro project. The additional details
96+
are:
97+
98+
- `src/collections` — This directory exports an array of collection
99+
configurations for use by the CMS. Each collection object contains the
100+
component used to render a collection item, its CSS, and a configuration
101+
object for Netlify CMS, telling it which fields it needs to edit it.
102+
103+
- `src/components/index.ts` — This file similarly exposes components that can
104+
be included in Markdown files. That means they also include configuration
105+
for what kind of inputs they need.
106+
107+
- `src/pages/admin/index.astro` — This page serves the admin dashboard for
108+
Netlify CMS.
109+
110+
- `src/scripts/cms.ts` — This script is imported by the `/admin` page and
111+
configures the CMS dynamically based on the components and collections
112+
above.
113+
114+
### Adding a new collection
115+
116+
_See `src/collections/posts/index.tsx` for an example._
117+
118+
1. Create a directory with the name of your collection under `src/collections`.
119+
120+
2. Write a component to render an item in the collection.
121+
122+
3. Export the component, its CSS (if any), and a collection object configuring
123+
it for Netlify CMS.
124+
125+
4. Add your collection to the export in `src/collections/index.ts`.
126+
127+
### Adding a new editor component
128+
129+
_See `src/components/Author.tsx` for an example._
130+
131+
1. Create a component.
132+
133+
2. Write a configuration object detailing the component’s inputs.
134+
135+
3. Add it to the `Components` and `CMSComponents` exports in
136+
`src/components/index.ts`.
137+
138+
[starter]: https://astro.new/blog?on=github
139+
[cms]: https://www.netlifycms.org/
140+
[proxy]: https://www.netlifycms.org/docs/beta-features/#working-with-a-local-git-repository
141+
[deploy]: https://app.netlify.com/start/deploy?repository=https://github.com/delucis/astro-netlify-cms
142+
[identity]: https://docs.netlify.com/visitor-access/identity/
143+
[gateway]: https://docs.netlify.com/visitor-access/git-gateway/
144+
[editor-components]: https://www.netlifycms.org/docs/custom-widgets/#registereditorcomponent
145+
[cms5065]: https://github.com/netlify/netlify-cms/issues/5065
146+
[astro2474]: https://github.com/withastro/astro/issues/2474

‎astro.config.ts renamed to ‎demo/astro.config.ts

File renamed without changes.

‎netlify.toml renamed to ‎demo/netlify.toml

File renamed without changes.

0 commit comments

Comments
 (0)