Decide and document how authors can contribute posts directly to the blog

[codersquid]

Denny wrote on the mailing list,

I am thinking it might be easier if we all could work with this ourselves. Could you recommend a tutorial for working with this markdown stuff?

Clearly we should do this. But we should go beyond explaining markdown. We should allow authors to edit files in the repo directly, and we should have docs explaining to users how to work on their own posts.

Given that not all authors are familiar with git, branches, merges, github, forks, and pull requests, we can explain how to use github's or prose.io's web interfaces for adding and editing files. We should add this documentation before adding documentation on using git.

We also need docs for explaining the ocs blog conventions for which pelican fields are required, how they are used, and what they are used for as well as provide example markdown files with comments explaining these things. Without this, documentation on adding files wouldn't be useful.

In order to avoid requiring users to understand branching and forks out of the gate, I think we could work around this by creating a draft branch and setting it as the default branch in the settings.

I think when authors use the web ui to add and edit files, those files will get added to the default branch. I have not tested this. I know that when I git pull repos that my local repo starts off on the default branch.

I do not have time to test this, but I wanted to open the issue up for discussion.

• test whether doing the branch trick works with the web UIs (it probably will)
• document pelican conventions used by the blog
• create example markdown files that follow the conventions
• document how to use the web UIs
• bonus round: see if it is possible to auto-populate new files created in prose.io with post templates. this is likely possible. read prose.io config.

[octern]

How does a draft branch work? Does it allow authors to see how a post will look when it's on the blog, without allowing them to freely edit live posts? That would sound reasonable to me.

We don't want to require all authors to learn markdown, so perhaps a good procedure would be to continue accepting submissions in any format, converting them to markdown ourselves, and then letting the author know the draft is available for them to edit further if they wish. Then they can tinker with edits and formatting on their own (that kind of tinkering is how I usually end up learning new markup / markdown / programming languages anyway).

[codersquid]

It does. I just tried it out in my repo. I create a branch called draft and set that as the default branch in github. The prose.io page opened in that branch. Prose.io and github both allow preview views of markdown files.

here's a prose.io preview screen