Integrating DecapCMS into an 11ty project
I decided I needed some sanity, so I looked into a cheap-to-run localhost-based Content Management System.
Coming from a WordPress system after many years, I feel a bit of distrust when I see most Content Management Features, and then the prices of cloud versions put me off too.
I considered using WordPress.com and pulling posts via API, but that option is likely rate-limited or unavailable for lower-tier plans.
The Setup
Installing DecapCMS via their Documents was easy, but configuring the environment is not. Lots of information then gets confused with itself (for example there are path parameters which show item: “string” and item: string). I Decided to keep my install local to stop Github being bothered by anything finding/crawling the admin directory.
Configuration
Here’s what I needed to change, hopefully, it’ll make sense to people needing that bit of help who’ve already seen the mess of documentation and GitHub issues.
# when using the default proxy server port
local_backend: true
backend:
# name: git-gateway
name: github
repo: YourGithubUser/ProjectRepo
# optional, defaults to master
# branch: main
site_url: https://Yoursite.domain
#site_url: http://localhost:8080/ # for testing
publish_mode: editorial_workflow
media_folder: "/assets/images/" #Your main image source if not in /posts.
#public_folder: 'images' # defaults to media_folder if not present.
collections: # A list of collections the CMS should be able to edit
- name: 'posts' # Used in routes, ie.: /admin/collections/:slug/edit
label: 'Posts' # Used in the UI
label_singular: 'Post' # Used in the UI, ie: "New Post"
description: >
The description is a great place for tone setting, high level information, and editing
guidelines that are specific to a collection.
folder: 'posts' # must match folder where Posts are.
# slug: '---'
slug: ''
summary: 'DecapCMS with 11ty -- //'
create: true # Allow users to create new documents in this collection
path: ''
editor:
visualEditing: true
view_filters:
- label: Posts With Index
field: title
pattern: 'This is post #'
- label: Posts Without Index
field: title
pattern: front matter post
- label: Drafts
field: draft
pattern: true
view_groups:
- label: Year
field: date
pattern: \d{4}
- label: Drafts
field: draft
fields: # The fields each document in this collection have
- { label: 'Title', name: 'title', widget: 'string', tagname: 'h1' }
- { label: 'Draft', name: 'draft', widget: 'boolean', default: false }
- {
label: 'Publish Date',
name: 'date',
widget: 'datetime',
format: 'YYYY-MM-DD', # removed HH:MM:SS as my 11ty setup didn't like it. also causes issues with sorting in /admin
default: '',
}
- { label: "Permalink", name: "permalink", widget: "string" }
- label: 'Cover Image',
name: 'hero', #name of frontmatter item to match
widget: 'image',
media_folder: '/assets/images',
public_folder: '/assets/images',
required: false
tagname: ''
- { label: 'Body', name: 'body', widget: 'markdown', hint: 'Main content goes here.' }I also had to fix up pages with a new section.
- name: "pages"
label: "Page"
folder: "pages"
create: false # Change to true to allow editors to create new pages
slug: ""
fields:
- { label: "Title", name: "title", widget: "string", tag: "h1" }
- { label: "Publish Date", name: "date", widget: "datetime" }
- { label: "Permalink", name: "permalink", widget: "string" }
- label: "Navigation" # https://www.11ty.dev/docs/plugins/navigation/
name: "eleventyNavigation"
widget: "object"
fields:
- { label: "Key", name: "key", widget: "string" }
- { label: "Order", name: "order", widget: "number", default: 0 }
- { label: "Body", name: "body", widget: "markdown" }And likely to add another for Projects when I have new ones to put up.
Security
I’ve decided to keep this localhost for the time being, adding the /admin folder to .gitignore so it doesn’t appear on the live site.
There are still some oddities, despite the repo being private, people can attempt to pull/write to branches once they know fork locations.
I Just have to remember to run ‘Decap-server’ as well as ‘11ty build’ in separate terminals.
Found Issues
- Post images ignore set paths in the config. I ran a filter for Cover images using the file name in frontmatter and the path added in the template and fixed it by reverting frontmatter to the full path and adjusting the filter. So Media_libary is pretty much write-only?
- The Admin User Interface displays thumbnails and in-post images pathed from /admin/filename, ignoring the paths set in the configuration. (fixed with the frontmatter changes listed above to every post).
- be careful of the ‘Rich text/Markdown’ switch, it got me a few times, and currently, the switch between the two is reversed for me.
- images called by manual markdown/html from the configured folder work fine, so it is something in Decap’s code not working.
- Live view on editor attempts to display frontmatter image URLs as the image but fails due to extra crap it adds to the name, for example: ‘http://localhost:8080/assets/images/11ty-output-binaryfile.png%E2%80%8B%E2%80%8B%E2%80%8B%E2%80%8B%E2%80%8C%EF%BB%BF%E2%80%8D%EF%BB%BF%E2%80%8B%E2%80%8D%E2%80%8B%E2%80%8D%E2%80%8C%E2%80%8D%E2%80%8C%E2%80%8B%E2%80%8C%E2%80%8D%E2%80%8C%E2%80%8C%E2%80%8C%E2%80%8D%E2%80%8B%EF%BB%BF%E2%80%8C%E2%80%8D%E2%80%8B%E2%80%8C%E2%80%8C%EF%BB%BF%E2%80%8B%E2%80%8B%E2%80%8B%E2%80%8D%E2%80%8B%E2%80%8D%E2%80%8B%EF%BB%BF%E2%80%8D%E2%80%8D%E2%80%8B%E2%80%8D%E2%80%8B%E2%80%8D%E2%80%8C%E2%80%8D%E2%80%8D%E2%80%8B%E2%80%8C%E2%80%8D%E2%80%8C%E2%80%8C%E2%80%8C%EF%BB%BF%E2%80%8B%E2%80%8D%E2%80%8C%E2%80%8D%EF%BB%BF%EF%BB%BF%E2%80%8B%E2%80%8D%E2%80%8B%E2%80%8D%E2%80%8C%EF%BB%BF%EF%BB%BF%E2%80%8C/’, this could be DecapCMS attempting to render it as a img tag. posts with CSS/HTML-based image trickery render fine.
Strikethroughdoesn’t seem supported in the editor, its tag ends up as ~~word~~
Information To add:
-
Tags widget, I tried a few things but can’t get it to work currently.- {label: "tags", name: "tags", widget: "list", default: ["posts"]}in the posts collection works for now. -
Gallery widget, not attempted yet.