klokantech/jekylledit

Jekyll Visual Content Editor for Customers - WYSIWYG web administration / CMS for GitHub Pages website

jekylledit

Jekyll Visual Content Editor - WYSIWYG administration with custom logins

Ideas at: https://docs.google.com/a/klokantech.com/document/d/1vA2CXiDdSmZXggVb-PFKBTIJ9rZQwd1QfYuYHOBgy7Q/edit?usp=sharing

Screenshot of first implementation:

jekylledit's Issues

Profile editing does not create new users

If the user is not present in users.json editing profile does not have any effect (the user should be added to users.json).

Timezones issues

Javascript should correctly compensate for various timezones.
Currently, javascript sends local time. This can cause the following issue:

• someone in Japan writes a new post at 14:00 local time
• the post is saved, but may not be compiled (unless future: true in _config.yaml), depending on the server timezone
• the post will be compiled somewhen in the future when any other change is done in the repo (after the local time passes in the server timezone) + the post time can be incorrect

Solution:

• Server can have any timezone (but possibly future: true just to be safe)
• Javascript uses local times, but saves proper timezone
• When editing post, the local time is also displayed (timezones may have to be converted)

Flask backbone

Core of the Flask application.

Notes:

• User creates manually "git clone" on the server where the Flask runs.
• Under the username are set SSH keys - so commands run authenticated against GitHub.
• Flask will call local "git" commands (such as commit, push, ...) on the previously manually cloned git repo.

JavaScript backbone

The core of the jekylledit javascript (popup window from "Edit" at - http://klokan.github.io/kartenportal/blog/announcements/viewer-zeitreise/)

Editable profile

custom fields for an author defined in jekylledit config.

On Kartenportal.CH used for libraries (openning time, etc) https://github.com/klokan/kartenportal/blob/gh-pages/_data/libraries.json on other pages just custom fileds (my hobbies, address, phone number, or whatever else).

Let's mock some fields in the jekylledit - and the discuss with @daliborjanak the endpoint for get / save.

Strip colon from title in permalink

ERROR: YOUR SITE COULD NOT BE BUILT:
                    ------------------------------------
                    The URL /announcements/landeskarte-1:10000-setzt-neue-massstabe/ is invalid because it contains a colon.

If the user adds title with ":" than jekylledit adds a colon to URL like:
permalink: /announcements/landeskarte-1:10000-setzt-neue-massstabe/
New Jekyll couldn't build the page wit this. We have to strip this.

Content attribute defintion

The list of different editable content + list of attributes and types (text, number, multiple choice, ...) for different pages.

A la:
https://github.com/prose/prose/wiki/Prose-Configuration#working-with-content-types-in-prose

Flask reads from jekylledit.yaml or from _config.yaml with jekylledit: section?

Filesystem locking

Processes operating on Git directories must be mutually excluded to prevent race conditions. We have been using the pid library for this in other projects.

https://pypi.python.org/pypi/pid/

$ pip install pid

from pid import PidFile

with PidFile(piddir='/path/to/dir', pidname='my.lock'):
    # This is the critical section. All processes with
    # the same pidfile path will be mutually excluded.
    pass

Jekylledit interface localization

The jekylledit interface itself needs to be localized ("Log in", "Cancel", "Save", ...).

Interaction after an email verification

If user verified an email that he see on page:

He should see a sign button.

Media upload

We need to upload images to a content of each post. Files will be stored in folder /<category>/media/ (default /media). We need to implement it in javascript and server endpoints (will be specified).

Draft notification via email

Admins of the website needs to be notified via email that an editor has submitted a new draft.

Flask Deploy

First deploy at https://jekylledit.klokantech.com/

Permalinks

We need to save permalink to a header on a server when a new post is created.

Required fields

Some post attribute fields might be marked as "required" in the config.
The interface should not allow the user to save the post if this fields is not filled in.

Save JSONs formatted

Currently profile and translations editing saves single-line json.
It should be formatted before it's written to the file so we better use the git's line-based diffs.

User data in token response

We need to add (to the /site/<side_id>/token response):

• User email (and name?) to be displayed
• User role for the repo
• Logout endpoint

Read-only attribute fields

Implement post attributes with type and default value, but readonly.
e.g. layout: "post":

  "layout": {
    "type": "text",
    "value": "post",
    "readonly": true
  }

User accounts via GitKit

Using GITKIT? https://developers.google.com/identity/toolkit/

Discussion with @keosak required.

Cross-domain secure login

Flow inspired by http://iiif.io/api/auth/0.9/:

• Send request to /auth/token endpoint (JSONP) (see http://iiif.io/api/auth/0.9/#jsonp-interaction)
  • cookies are sent with the request
  • based on the cookies, returns access token (or null if not logged in)
• If not logged in, open new window/tab on /auth/login where the user can log in (see http://iiif.io/api/auth/0.9/#step-3-user-authenticates)
  • After the login finishes
    • cookie is create to authenticate the user in the future
    • the success page tries to close the window
• The original javascript detects the window is closed and re-requests the token

After that, all requests on the jekylledit domain are authenticated either by:

• the cookie (simple resource requests -- images, ...) -- probably not needed
• the token passed in header Authorization: Bearer TOKEN_HERE (XHR requests)

Permalinks and files with quotes

Related with https://github.com/klokan/kartenportal/issues/69
We have to improve slugging of a title. Quotes are not replaced. This line:
https://github.com/klokantech/jekylledit/blob/master/app/jekylledit/controllers/site.py#L88

Administrator can edit other urser profiles

• Endpoint which returns all users only to administrator /site/<site_id>/users
• Create /site/<site_id>/user/<user_id>/profile (user_id == base64(email))
• Create userswitcher in jekilledits profilediting only for administrators.

A installation guide and Documentation

Hey!
Is there any documentation or a installation guide available for use?

OAuth for cloning local git repo

I have realised that OAuth can be used to create the clone (including write access) to a repo.
This means the @jekylledit user would not need to be used at all - and after installation of the JekyllEdit - the web could just ask the admin user for his GitHub OAuth permission to GitHub and clone the repo he specify for him.

This will make first deploy significantly easier.

Cloning is done this way:

git clone https://<token>:[email protected]/owner/repo.git

(from https://github.com/blog/1270-easier-builds-and-deployments-using-git-over-https-and-oauth)

To request the OAuth token there is a simple Web Application Flow - https://developer.github.com/v3/oauth/#web-application-flow
@o1da is using it already in our clientportal project.

The application Client ID / Client Secret is registered under klokantech organisation.
It could be passed to Docker via a system variable - so non-klokantech deploys are easy.

Multilingual posts

We have languages in the config.
When creating new post, the editor interface saves all languages at once (POSTs object with multiple language versions):

{
  "en": {
    "metadata": ...
    "content": ...
  },
  "de": ...
}

and this is saved in a single commit.

When editing existing post, the interface sends GET to /site/<site_id>/<post_id> and should get the same structure as above (all language variants).

Each language version has separate attributes and content. Following attributes have special meaning in this context:
post_id -- unique (random) post id identical for all the language versions
lang -- id of the language variant
jekylledit_copyof -- if this attribute is present on the language version, it says from which language this version was derived without changes. (e.g. jekylledit_copyof: "en" on it version says that the italian version is 1:1 copy of the english version)

Dashboard interface

List drafts and show buttons for new posts.

Improved user messages

• Verification notice:
  Add bellow a new line/block: "Please check your email and click on the confirmation link."

- [ ] Email - add information about the "site" / "base_url" ("beta.kartenportal.ch"). Details TODO.

Drafts

User with role "editor" always saves drafts.

User with role "admin" can save a draft, or publish directly.

When editor creates a draft - all admins receive email notification.

Endpoint for getting the list of drafts - admin of all drafts, editor for his own.

Github webhook

We need to create endpoint which is pulling new changes from Github. Hook on /site/<site_id>/update will pull called repository from remote

Tag refactoring

The user should be able to also add custom tag (not present in the current tag list).
When the happens the tag should be visible in the autocomplete tag list.

Solution:

• jekylledit.json can contain URL instead of the list of values @petrsloup
• The autocomplete in the sidebar displays values from this json @petrsloup
• The autocomplete also allows to add new (never used before) value and save it @petrsloup
• The jekyll backend automatically rebuilds the json with tags (iterate all the posts)
• We can have multiple tag lists (e.g. different tag list for each category) by building multiple jsons and using different urls for tags field in each category in jekylledit.json

Category branding

Each category has an icon, name etc. defined in config JSON.