Feature Request: Method to edit content for non-techical contributors

[fifieldt]

We have the potential (and need) to significantly expand he number of contributors to the content portion of our website.

The current editing process works well for those with knowledge of git, the command line and markdown syntax. However, it also means that 100% of our contributors come from a technical background.

We need a way that people who have excellent writing skills but no technical ability can just jump in and propose changes. This should be something they can run through their browser.

The implemented feature should ensure that the edits proposed by new editors is subject to approval before publication, and that all edits are tracked in version control and attributed to individuals.

[pqvst]

I have explored "CMS" editors that work on top of GitHub/markdown in the past, but never found one I felt worked well. For example: prose.io or cloudcannon.com - Maybe there are some other options for hugo (instead of jekyll).

[fifieldt]

On my reading list:

https://www.portent.com/blog/copywriting/content-strategy/content-with-github-markdown.htm

[fifieldt]

I have looked up a few markdown editing tools:

• Dilinger.io - web based, has github integration (can commit to a branch, but no pull request), but unfortunately can only load one file at a time and requires many clicks to do so. It also required editing in markdown, though it does have a live preview.
• Typora - beautiful and simple WYSIWYG editor with a great outline view of all the files that make it easy to change files in multiple areas. No git integration and this is not planned by the author. Available for all platforms.
• prose.io - web, based, with github integration that works intuitively (though still no pull request workflow), and can create new files. also supports published/unpublished toggle. However, editing view is still raw markdown.
• pen - http://sofish.github.io/pen/ - web-based WYSIWYG for markdown, no file/import export.
• https://stackedit.io/app - web based, quite similar to dillinger.io, but github setup requires manual configuration and can only open one file at a time.
• iaWriter, non-free
• Ulysses only for apple systems.

Looking into hugo-specific options

• https://github.com/zzamboni/enwrite
• https://github.com/SohanChy/Lipi
• https://www.netlifycms.org/
• https://github.com/netlify-templates/one-click-hugo-cms
• https://github.com/julianoappelklein/hokus
• https://github.com/titpetric/pendulum
• https://forestry.io/
• https://www.datocms.com/cms/hugo
• https://github.com/stayradiated/rango
• https://github.com/18F/federalist uses netlifycms
• https://github.com/julianoappelklein/hokus

[fifieldt]

I think an ideal workflow for us would be

1. Writer opens a website, makes edits in a WSYWIG editor, clicks save
2. A pull request is opened on github, which Experienced Folks can approve
3. On approval, the writer gets credit for contributing to the website.

Conclusions so far:

• Just getting a multi-platform WYSIWYG editor for markdown isn't trivial
• There's nothing planned that will automate the creation of a branch and a pull request, linked with a WYSIWYG markdown editor

I am intrigued by Federalist, which was specifically created for government agencies. It looks like that might have the concept of an 'approved' version of the content and a draft version that is implemented in git.

[iansinnott]

What's the reasoning behind a pull-request based workflow?

I'm thinking maybe there's a platform that has solved content contributors needing authorization to publish. I bet this is a solved problem, it just doesn't fit into a pull-request workflow.

---

Aside: Editing markdown on github is a decent stopgap measure IMO. It is indeed markdown, but formatting is far less important than the content itself, so contributors could add really meaningful content without needing to understand MD specifics.

[fifieldt]

Hi @iansinnott , I really appreciate you questioning assumptions - it's very valuable at this stage.

I suppose the underlying factors we're trying to hit are

• large group can make contributions with a low barrier to entry
  • these are not immediately published, but instead put up for review
  • who makes the contribution is tracked
  • which part of the text that is changed is tracked
  • when the change is made is recorded
• small group can validate the changes and choose to publish them
  • this group requires usernames/accounts/etc

these can of course be achieved outside a pull request workflow, I was just aiming to reuse as much as possible of what we have right now.

I agree that editing on github is a nice stopgap - I believe that's how Jonathan edits. The problem comes when needing to synch a fork with master, I think.

[geekyme]

Tried forestry.io today. It works quite well, zero-code change. Here are some screenshots:

For PR workflow, what about doing something proposed like this:

1. Forestry CMS allows non-technical folks to edit content on the preview branch.
2. Our CI will deploy staging site from preview branch.
3. If all looks good, developers can then open a PR to "promote" preview branch to master
4. CI deploy production site from master branch as usual

[iansinnott]

I agree that editing on github is a nice stopgap - I believe that's how Jonathan edits. The problem comes when needing to synch a fork with master, I think.

Oh totally forgot to reply to this. Heh... I was thinking you just edit on master 😑

@geekyme is that the forestry workflow out of the box? Or would we need to set up some "real" CI beyond the ./deploy.sh script?

[erickhun]

oh really nice @geekyme !

I didn't test forestry but :

• are all pages we have work on forestry (thinking about the profiles page : https://github.com/taiwangoldcard/website/pull/44 ) ?
• custom domain name is free?

[geekyme]

@iansinnott Forestry doesn't support any workflow out of the box. So therefore we'll still need to rely on our own CI / scripts for the branch promotion.

What forestry appears to do well is it's synchronization with our GitHub files. So all our pages seems to appear on forestry for us to edit. We can create new pages from forestry too. @erickhun

Do we also need a custom domain name for the CMS? I'm guessing not since it's an internal tool.

Maybe I can invite you guys to try on my instance? You can send your emails on our line group.

[geekyme]

https://www.netlifycms.org/docs/configuration-options/

Just had a closer look on this. Looks like netlifyCMS’s editorial workflow fits what we want for the PR workflow too

[pqvst]

Netlify CMS looks pretty interesting. It looks like it's open-source (✅). But, can it be hosted/used anywhere (i.e. it doesn't lock us into using Netlify)?

[geekyme]

It can be hosted anywhere (but that brings complexity if we run it).

Overall, I'm still on the fence with NetlifyCMS. What I don't like:

• Code change required for "setting up" the admin panel. Every time you have some new file that needs to be editable in netlifyCMS, you need to configure it in code. Forestry don't have any code change.

• Backend for Auth / file querying / file saving is needed if we don't want to use netlify. https://www.netlifycms.org/docs/backends-overview/

• UI is very basic. I don't think you can edit the front matter. I think frontmatter should be editable otherwise people can't easily change things like title / weight. Forestry wins here.

Still looking to see if we can find a forestry-like CMS w/ PR flow. But I think if we can't find it, perhaps we should re-consider whether we need this PR flow.

[geekyme]

Ok folks, I take back what I said about Netlify CMS. Had a chance to dive a bit deeper today.

PR flow works, check out the list of PRs auto managed by netlify CMS.

Front matter editing works, and preview also works:

They even got a neat kanban board to show any new posts you are creating that's still under review:

Next steps:

1. I would like to invite you guys to try it @taiwangoldcard/tech , lets continue this discussion in slack and give me your emails there.

2. Depending on whether you guys like it, I can then make a PR to the master with my changes.

[erickhun]

love this @geekyme . This will definitely unlock non-code person to add/edit the content

As said on slack, my concern is the Review process where everyone can publish it . But in the other hands, it’s like our process in github - everyone can merge the PR or push to master, so it isn't really a problem?

If we all agree and go ahead :

• Should we just trust everyone in the project to only put edit at a In Review state?
• How the review process will work?

[fifieldt]

If you are worried about that stuff (or for the future), what I recommend is that the CMS is hooked up to a branch other than master. Then you can allow the world to edit, but people with repo rights merge in the edits to master

[erickhun]

yes @fifieldt

An other issue is the ability to see what was the change in the netlify cms UI. Someone reviewing the change there wouldn't actually see what was the change .

So this would be tho workflow:

• Someone publish change in netlify
• this create a PR to GitHub ( is it possible?)
• PR is approved refused (but what happen for discussions? people will have to switch between netlify and GitHub?

(this flow sounds a bit over-engineered and with lot of friction imo)

[fifieldt]

Yup ... if we want a workflow that involves 'approval' before publication that sounds about like how it would end up.

Another option might be to accept changes by default and then revert if issues are encountered.

[geekyme]

this create a PR to GitHub ( is it possible?)

Yes for example this PR is created by netlify - https://github.com/geekyme/taiwan-goldcard-website/pull/9

PR is approved refused (but what happen for discussions? people will have to switch between netlify and GitHub?

Unfortunately discussions probably in github.

A lot of friction indeed.

[geekyme]

Ok guys, I found a flag in netlify CMS that helps things a bit regarding the lack of roles. publish: false. This flag will hide the functionality for CMS users to publish.

TLDR; CMS = For people to propose edits. Github = For people to approve and merge.

They can only propose edits. Heres the flow:

1. User create / edit a page in CMS.

2. Once they save, a PR automatically gets created at our repo:

3. They can set the status in netlify CMS to "Ready", then the github tags automatically change

4. Once merged, site automatically deployed & updated as usual:

5. CMS status will be automatically updated to publish on merge:

WDYT @fifieldt @pqvst @erickhun @iansinnott ?

[iansinnott]

Awesome, thanks for figuring this out @geekyme

[unfulvio]

Probably I'm late for this or maybe it has been mentioned already, but how about https://getpublii.com

[geekyme]

yep checked out publii as well. I prefer netlifyCMS as it doesn't require a desktop program to be run for editing the site.