docs: Update bundling documentation with an example using Astro #358
Conversation
This is my best attempt at providing more detailed instructions. I'm not entirely onboard with how the config is loaded using: `import config from './config'` and `CMS.init({config})`, which is why my description might not be accurate regarding how it actually works, but I documented my own understanding as best as possible.
I will be writing an example using Astro in another commit
✅ Deploy Preview for demo-staticjscms ready!
To edit notification comments on pull requests, go to your Netlify site settings. |
✅ Deploy Preview for staticjscms ready!
To edit notification comments on pull requests, go to your Netlify site settings. |
Skrubbadubba
changed the title
| @@ -32,9 +38,24 @@ CMS.registerPreviewTemplate('my-template', MyTemplate); | |||
|
|
|||
| **Note**: Wherever you initialize Static CMS (via `CMS.init()`), it takes over the current page. Make sure you only run the initialization code on your CMS page. | |||
|
|
|||
| If the CMS object is initialized without being passed an object with a valid config attribute, it will try to fetch and read a `config.yml` or `config.js` file, via http, within the same path where the CMS resides (`/admin/config.<js/yml>`). | |||
There was a problem hiding this comment.
I'm not sure this is right. This is how it looked to work to me after some trial and error.
There was a problem hiding this comment.
It only tries to load config.yml.
| @@ -12,17 +12,23 @@ To get started you need to install Static CMS via a package manager and save it | |||
|
|
|||
| ```bash | |||
| // npm | |||
| npm install @staticcms/core | |||
| npm install @staticcms/core@next | |||
There was a problem hiding this comment.
This will obviously be changed after 1.0.0 release, but I thought this should be added, as the docs should ideally only show working code.
| CMS.registerPreviewTemplate('my-template', MyTemplate); | ||
| ``` | ||
|
|
||
| **Note**: Because `config.<js/yml>` is requested via http, make sure `<siteurl>/admin/config.<js/yml>` exists as an endpoint on your build. If the file is not placed in the public folder, this might not be the default behaviour for your framework. |
There was a problem hiding this comment.
"framework" or "static site generator". Wasn't sure what was most appropriate
There was a problem hiding this comment.
static site generator
chore: writing mistakes
| @@ -32,9 +38,24 @@ CMS.registerPreviewTemplate('my-template', MyTemplate); | |||
|
|
|||
| **Note**: Wherever you initialize Static CMS (via `CMS.init()`), it takes over the current page. Make sure you only run the initialization code on your CMS page. | |||
|
|
|||
| If the CMS object is initialized without being passed an object with a valid config attribute, it will try to fetch and read a `config.yml` or `config.js` file, via http, within the same path where the CMS resides (`/admin/config.<js/yml>`). | |||
There was a problem hiding this comment.
It only tries to load config.yml.
|
|
||
| ```js | ||
| import CMS from '@staticcms/core'; | ||
| import config from './config.js'; |
There was a problem hiding this comment.
Under most build systems the .js on the end is unnecessary.
| import config from './config.js'; | |
| import config from './config'; |
| CMS.registerPreviewTemplate('my-template', MyTemplate); | ||
| ``` | ||
|
|
||
| **Note**: Because `config.<js/yml>` is requested via http, make sure `<siteurl>/admin/config.<js/yml>` exists as an endpoint on your build. If the file is not placed in the public folder, this might not be the default behaviour for your framework. |
There was a problem hiding this comment.
static site generator
|
|
||
| Make sure the file containing the CMS object will be built as a page, with `@staticcms/core` bundled, and the code including `CMS.init()` being run inside a script tag. This is what might take some time, as it will be done differently based on your framework. Check your framework's documentation for further details. | ||
|
|
||
| ### Example using [Astro](https://astro.build) |
There was a problem hiding this comment.
Right now I would like to avoid having any framework/platform specific details in the guide. Having that in here makes this into a maintenance issue, due to having to keep up with the platform in question to ensure our docs are accurate. I do not have the time, nor is our community big enough yet, to support that.
This is my attempt at clarifying the bundling docs. I tried to look at the code, but I didnt understand that much. My understanding of how things work (specifically with regards to loading the config), is mostly from trial and error. This means I might have just written a bunch of garbage, but I tried.
Although since I got bundling to work with Astro, I can say for sure that the provided example is valid.