Netlify-cms: A proposal for reorganizing the NetlifyCMS Docs navigation

Created on 16 May 2020 · 5Comments · Source: netlify/netlify-cms

👋 This is a proposal for reorganizing the navigation on the NetlifyCMS docs site. The goal is to make it easier for users to find the guidance they need.

A proposal for a new navigation structure

In short, there are a few things I was trying to do here:

group guidance around the decisions users are trying to overcome
make it easier to find help around the challenge you're facing
keep naming of the docs consistent with the components and code

Better packaging

As an editor, there are different types of decsions I need to make when setting up NetlifyCMS, each with it's own effect on the way my site will grow over time. Some of these decisions are foundational to integrating with your platform, others affect how your editors will develop habits and workflows over time. Setting up a CMS is important work and if done well, it can have a huge impact on the confidence of the team that is responsible for the site day-to-day.

To get there, I think we need to group pages under headings that reflect the decisions that users would need to consider and the challenges they're trying to overcome when setting up NetlifyCMS.

Each decision area should have

An overview that helps to orient people, explains the terminology and how to think about these settings and the effect they'll have on your site.
A list of pages for this decision area _(for the most part, these are already there)_
Examples – a page where people from the community can leave
Community discussion – a link to a cooresponding page in the community https://community.netlify.com/c/netlify-cms/31

NetlifyCMS Docs Navigation

https://www.netlifycms.org/docs/intro/

Quick Start

Introduction
Releases
Start With A Template
Add To Your Site

Configuration

Overview
Configuration Options
Update the CMS Version
Beta Features! ---------------- _👈 more on unpacking this at a later point_
Examples
Community discussion

Workflow

Overview
Deploy Preview Links
Open Authoring
Examples
Community discussion

Backend

Overview
Git Gateway
Bitbucket
GitHub
GitLab
Test
External OAuth Clients
Examples
Community discussion

Media

Overview
Cloudinary
Netlify Large Media
Uploadcare
Examples
Community discussion

Collections

Overview
Collection Types
Examples
Community discussion

Fields

Overview
Boolean
Code
Date
DateTime
File
Hidden
Image
List
Map
Markdown
Number
Object
Relation
Select
String
Text
Examples
Community discussion

Platform Guides

Overview
Gatsby
Hugo
Jekyll
NextJS
Nuxt
Middleman

Customization

Overview
Creating Custom Widgets
Creating Custom Previews
Examples
Community discussion

Contributing

Overview
Contributor Guide
Writing Style Guide
Architecture

docs feature

Source

jeremyzilar

👍7 ❤6

All 5 comments

Would love to see a re-org like this, the community has needed it for some time. Thanks for putting this together!

erquhart on 16 May 2020

❤1

In looking at the top-level sections more closely, I think I would probably want to name them a bit different than what I proposed above.

Intro to Netlify CMS
Account Settings
Configuring your Site
Media
Workflow
Collections
Fields
Platform Guides
Customizing Netlify CMS
Community

jeremyzilar on 16 May 2020

I ran into an issue outlined in https://github.com/netlify/netlify-cms/issues/3769

With regards to the Gatsby integration, I think the suggested approach should be to go with gatsby-plugin-netlify-cms over the netlify-cms package outlined here. The gatsby plugin is based on the updated netlify-cms-app package, whereas the Netlify docs that I linked are still using the netlify-cms package.

With the gatsby plugin, no admin/index.html is required. As per the netlify-cms documentation, it's listed as a requirement.