Draft: Nested collections

[erquhart]

Is your feature request related to a problem? Please describe.

A site's page hierarchy can require pages and groups of pages to be created in a nested structure. A content editor working with such a site may need to:

• create new pages at various levels of the hierarchy
• create entirely new hierarchy levels within existing levels

Netlify CMS allows new entries to be created in folder type collections, but all entries are more or less siblings in the collection folder. Collections must be added to the CMS configuration for each level of hierarchy.

Describe the solution you'd like

Known use cases involve a single collection description requiring hierarchy only - not distinctly defined collections within other collections. Satisfying this feature request should be doable by simply "enabling nesting" on a folder collection.

• Allow a collection to contain nested directories
• Allow nested directories to be created through the CMS UI
• Allow entries and nested directories to exist in the same parent directory

Configuration

• Activate by setting an allow_nesting property to true on a collection
• An optional max_depth setting limiting how deep the hierarchy can go
• max_depth should default to something sane like 3
• max_depth should have an internally enforced and documented limit, maybe 5
• label_singular can apply to all nested directories

UI

• Collections with nested directories should show as dropdowns in the left sidebar
• The dropdown should only show directories, not entries
• A single folder can be selected at a time
• Only entries directly located in the currently selected folder are visible in the main entries pane
• An "add" button should show underneath the last nested directory at any level (when expanded)
• When clicked, a new directory icon is created in its place with an input for naming the new folder

Stretch Goals

• Drag and drop directory movement in the tree (perhaps w/ react-sortable-tree)

Implementation Considerations

• Nested entries accessed directly via the /edit/ route, the entryName segment currently refers to the filename, but should refer to the path from collection folder to file for nested collections

Open Questions

• We need a way to rename and delete directories in the UI
• Creating and editing directories can often result in URL changes, admins will need a way to guard this functionality
• How do we avoid using raw folder names in the left sidebar? Nested content structures often have a _index.md or index.md file at each level, ideally we could pull values from there for string replacements in the label and description fields.
• If index.md style files start playing an important role, we need a way to require them in new directories

Describe alternatives you've considered

• Not supporting nested directory creation
• Supporting distinct collections nested with other collections
• Adding a config UI to the CMS (Generate and edit config through CMS UI #341) and allowing collection creation there

Additional context

Related to:
#513

[BranonConor]

Hey @erquhart, this is all a great request. I am following along with this and with #341 as my project requires admins (non-developers) to create / edit new pages at will (ideally with customization about their position in the directory). Looks like request #341 has been in consideration for a while. Any prospective solution for it in the near future? Any current workarounds? Thanks for your hard work and cheers man.

[erezrokah]

Hi @BranonConor, we try to handle most up voted issues first so best thing to do is up vote #341.
#341 (comment) might serve as a work around and there is some ongoing community effort to re-design the UI here #341 (comment)

[joshdcomp]

Voted, but also wanted to voice support for this feature…we're doing quite a bit of hoop-jumping to get around the limitation of no nested dirs in folder collections

[zabatonni]

Not working for standard hugo structure. At least for me, or am I missing something?

I have this content structure:

And get this output in cms:

this is my config in js:

collections:[
		{
			name:'pages',
			label:'Pages',
			folder:'content',
			nested:{depth:1000},
			meta:{path:{widget:'string',label:'Path',index_file:'_index.md'}},
			create:true,
			fields:[
				...fields.common,
				...fields.seo
			]
		}
	]

[zabatonni]

Think i found problem. It only works if files are named _index.md and placed in corresponding folder like this:

Its definitely doable and a way to go with this project.

Thanks for this awesome feature.

[alex-shpak]

Hi! @erezrokah
Thank you for your huge effort, not having nested collections was stopping me from using netlifycms.

Question in regard file structure mentioned above, would structure like that work?

level1/
  _index.md
  level2/
     _index.md
     level3.md
     otherPage.md

A mix of regular pages and _index.md pages, (Hugo in this case).
Or every page must be a folder with _index.md?

[zabatonni]

After setting meta path in collection config:

meta:{path:{widget:'string',label:'path',index_file:'_index.md'}}

I get this error every time I try to save existing content:

Failed to persist entry: API_ERROR: A file with this name already exists

I'm using gitlab backend with netlify cms application to log in.
If I create new content it saves ok, but after editing same error appears.

If I comment line with meta.path, I can save and work with content as expected, but I'm not able to move content to different folders.

With github backend it works as expected.

[zabatonni]

Hi! @erezrokah
Thank you for your huge effort, not having nested collections was stopping me from using netlifycms.

Question in regard file structure mentioned above, would structure like that work?

level1/
  _index.md
  level2/
     _index.md
     level3.md
     otherPage.md

A mix of regular pages and _index.md pages, (Hugo in this case).
Or every page must be a folder with _index.md?

After my testing, for Hugo you can use only folder/_index.md for every page

[erezrokah]

Please see the description of the feature/assumptions here #3716

I'll update the docs with the expected structure.

If you have any issues, please open a new issue with a reproduction since it makes it easier to track things.

[timbomckay]

Is there a way for the path field to be optional? Like if I don't provide a path it would default to the root, or am I missing something? It'd be great if this were a select or combobox field to select an existing page as the parent, but I'll assume it's been considered.

[timbomckay]

Is that meta object new? I couldn't find any documentation on it other than in this nesting feature. Didn't know if there were other parameters or values available, like if the widget can be anything other than a string.

[erezrokah]

Is there a way for the path field to be optional? Like if I don't provide a path it would default to the root, or am I missing something?

Setting it to an empty value should write the index file at the top level.

It'd be great if this were a select or combobox field to select an existing page as the parent, but I'll assume it's been considered.

You can use any widget, for example we have an experimental parent widget:
https://github.com/netlify-labs/netlify-cms-widget-parent/blob/d3704ae278436739f04bf47505e694fff5c261d3/example/config.yml#L19

Is that meta object new?

Kind of new, it was used a long time ago and deprecated. Now it's only used for nested collections

[timbomckay]

Thanks for the response. When I try to create a new page I get this error

PATH IS REQUIRED. '%{PATH}' IS NOT A VALID PATH

I have this configuration

allow_nesting: true
# adding a meta object with a path property allows editing the path of entries
# moving an existing entry will move the entire sub tree of the entry to the new location
meta: {
    path: {
        widget: string,
        label: 'Path',
        index_file: '_index'
    }
}

[erezrokah]

Hmm, maybe I didn't remember correctly, can you try setting it to /?

[timbomckay]

If I open an existing page, such as /entries/about, it's set to / by default but when I try to publish it says

PATH '/' ALREADY EXISTS

I'm using the CDN which appears to be pulling in this script:

https://unpkg.com/[email protected]/dist/netlify-cms.js

Not sure if I need a beta version or something.

Thanks for the assistance.

[erezrokah]

No need for a beta version - how about opening a new issue with a reproduction?

[timbomckay]

Issue posted: #4317