We need guides.

[erquhart]

We need to write a whole lot of guides and pile them into the docs.

Let's keep a list of topics here. Suggest topics via comments, use reactions to +1 your favorites.

---

General

• Controlling Filenames
• Common Errors
• Troubleshooting
• Using with CSS-in-JS (some good solutions in Hard to use with CSS-in-JS libs. decap-cms#793)
• Working with Images
• Publishing with Editorial Workflow
• Authentication, including all options and Git Gateway w/o Netlify

Authentication

• Working with self hosted git-gateway
• Working with self hosted go-true (possibly with SSO)

Static Site Generators

• Using Netlify CMS with Jekyll
• Using Netlify CMS with Hugo
• Using Netlify CMS with Gatsby
• Using Netlify CMS with Next
• Using Netlify CMS with Hexo
• Using Netlify CMS with VuePress
• Using Netlify CMS with Nuxt
• Using Netlify CMS with Docusaurus
• Using Netlify CMS with Middleman
• Using Netlify CMS with Eleventy

[tech4him1]

I think we should also create a list of "common" errors and how to solve. For example, Git Gateway not being turned on. Would a separate issue be better for this?

[talves]

I have even envisioned the errors send a url that links to the docs to explain how to fix or read about that part of the configuration.

[erquhart]

@tech4him1 that would be a solid guide, maybe call it Troubleshooting? Or something? But yes yes yes. Added both "Troubleshooting" and "Common Errors", feels like a good delineation.

@talves very much agreed, but should go to a separate issue. The goal if this one is to end up with just a ton of static guides, so that the only work required is writing documentation.

[krismorf]

Claimed the Gatsby guide

[adamwatters]

Just started working on one for Jekyll

[erquhart]

Awesome!!

[steffenz]

Hi! I just built a site with NextJS and Netlify CMS, and would love to give something back (and get to know the community) by contributing with a guide! 😁Is it still "up for grabs"?

[talves]

@steffenz yes. You can definitely start working on it. Just start it and do a PR with [WIP][Guide] in the beginning of the title and we will mark it as being worked on.

Thanks for contributing!

[tomrutgers]

Started working on a middleman guide

[adamwatters]

Finally got to the Jekyll guide - decaporg/decap-cms#2248. I'm planning on giving it a second pass in the coming days, but should be ready for another set of eyes if anyone wants to help with revision.

[morkro]

Why only documenting site generators? I am successfully using Netlify-CMS with a plain Vue.js and vue-i18n integration*. Would it be of interest to also provide guides for these implementations?

* https://github.com/morkro/euromat

[erquhart]

@morkro a plain Vue guide would be fantastic!

[nikosolihin]

Just taught a workshop with Eleventy and Netlify CMS. Would love to claim the guide for it!

[erquhart]

Have at it!

_{Sent with GitHawk}

[jballe]

I could probably write a guide on using Hugo

[erquhart]

That would be great!

[cdvillard]

Gridsome has a plugin with documentation on how to install Netlify CMS. Would that suffice or would a local doc be more appropriate?

[tomrutgers]

@cdvillard We'd like to add it to our own docs so people can find their way to it within the Netlify CMS
project. Converting the Gridsome documentation to a docs entry within the project shouldn't take much effort I suppose

[tomrutgers]

@steffenz could you comment on that?

[erquhart]

Thank you Henry!! Left some feedback on your PR 👍

[adamayd]

I'll claim the VuePress doc if no one else has it. Also @cdvillard and @tomrutgers was the Gridsome doc spoken for or was that just a conversation about how to do it? I could claim that one as well if it's needed.

[erquhart]

Both are up for grabs, that would be awesome!

_{Sent with GitHawk}

[brentjayingram]

@erquhart Can I work on the Using with CSS-in-JS ?

[ZoltanVeres]

I'm surprised we don't have an Eleventy Guide yet, i'm planning on working on it, because i need it for my personal blog.
@nikosolihin Are you working on this or is it up for grabs?
I identified two eleventy starters where Netlify CMS is in use, here are the changes related to NetlifyCMS:
https://github.com/danurbanowicz/eleventy-netlify-boilerplate/commits?author=biilmann
https://github.com/hankchizljaw/hylia/commits?author=erquhart

The setup used on Hylia is much sophisticated (made by @erquhart ) and it's closer to my needs but the builerplate starter (by @biilmann )seems easier to digest which is closer to what we have for the other starters. So i'm not sure which route should i go.
Any thoughts @erquhart ?

[erezrokah]

How about adding a guide on how to run the CMS without Netlify Hosting:
decaporg/decap-cms#2695
decaporg/decap-cms#2774

[umutykaya]

@erezrokah It could be great to have a guide for working with aws amplify.

[mdartic]

I don't see any guide started for VuePress.
I could make a PR to create this guide.
@erquhart do you have a guide to create a guide ?
I can create one from ideas of others SSG, if it's ok for you.

[adamayd]

@mdartic I failed miserably on my VuePress attempt then lost track of it, please take over.

[massoudmaboudi]

docusaurus

[d-sanderson]

Can we have a section dedicated to registerEditorComponent? I am looking for docs that explain the fromBlock function and can't find anything beyond this https://www.netlifycms.org/docs/custom-widgets/#registereditorcomponent

[Alexa-Green]

@massoudmaboudi Are you working on the docusaurus guide or should I?

[erquhart]

@Alexa-Green I think that was just a suggestion, I'd say go for it

[emileswain]

I second @d-sanderson suggestion regards a guide for custom components that cover a lot more detail that the current guide provides.

Attempting to go beyond 'hello world' instantly chucks developers into a rabbit hole of despair.
Issues i've yet to resolve (not quite ready to just give up yet)

1. Properly deploy custom widget to github repo and include in cms (before deploying to npm).
2. Create custom editor widget that embeds react code into markdown. (various issues and tests of patience yet to be resolved)
3. Not immediately obvious how to register custom components (I'm on NextJS static site gen).
4. Create custom widgets that work together. I can get a single markdown widget to work, but now it conflicts with the others. So there is clearly some magic with the regex detecting the widget code that i'm doing wrong, but there is zero documentation on this.

When you see a component someones written you like and bring it into your netlify CMS package, it becomes incumberant on your build process. this makes it very hard to leverage your components as a guide for custom components of our own.

Its very disparaging.

[beriberikix]

@Alexa-Green or @erquhart were either of you still planning on writing a docusaurus guide?

[erezrokah]

@Alexa-Green or @erquhart were either of you still planning on writing a docusaurus guide?

I don't think anyone is actively working on a Docusaurus, if you'd like to contribute it.

[aentwist]

As JavaScript framework churn continues, and as a result of the highly divisive Vue 3 release, I suggest dropping VuePress in favor of VitePress. FYI

However, maintaining two SSGs in parallel isn't sustainable, so the Vue team has decided to focus on VitePress as the main recommended SSG in the long run.

See What About VuePress?

.....maybe this should be its own issue

[privatemaker]

Hey everyone 👋🏻 in the spirit of our efforts re-booting Decap CMS and various documentation sprints, I've triaged all the missing guides from this list for easier tracking and coordination and closing this issue.

If any of you who mentioned contributing in the past (we realize it's quite a few years ago now), were interested we'd love your contributions, specifically:

• @nikosolihin @ZoltanVeres Add guide for using Decap CMS with Eleventy #33
• @brentjayingram Add guide for using CSS-in-JS #35
• @aentwist Add guide for using Decap CMS with Vue / VitePress #31

Also feel free to pop by our Discord server to connect!