From 92615f6183c94c039d7591068768ae21ce6e0b11 Mon Sep 17 00:00:00 2001 From: Aaron Parecki Date: Fri, 6 Jan 2017 11:00:34 -0800 Subject: expand documentation --- views/docs.php | 67 ------------------------------------------- views/docs/creating-posts.php | 15 ++++++++++ views/docs/editor.php | 46 +++++++++++++++++++++++++++++ views/docs/index.php | 29 +++++++++++++++++++ views/docs/note.php | 40 ++++++++++++++++++++++++++ views/docs/post-status.php | 10 +++++++ views/docs/signing-in.php | 37 ++++++++++++++++++++++++ views/docs/syndication.php | 38 ++++++++++++++++++++++++ 8 files changed, 215 insertions(+), 67 deletions(-) delete mode 100644 views/docs.php create mode 100644 views/docs/creating-posts.php create mode 100644 views/docs/editor.php create mode 100644 views/docs/index.php create mode 100644 views/docs/note.php create mode 100644 views/docs/post-status.php create mode 100644 views/docs/signing-in.php create mode 100644 views/docs/syndication.php (limited to 'views') diff --git a/views/docs.php b/views/docs.php deleted file mode 100644 index 7c6757d..0000000 --- a/views/docs.php +++ /dev/null @@ -1,67 +0,0 @@ -
- - -

Introduction

- -
- -
- -

This is a simple Micropub client for - creating text posts on your own website. To use it, you will need to turn your website - into an OAuth provider, and implement a Micropub endpoint that this app will send - requests to.

- -

Once you've signed in, you'll see an interface like the one shown which you can use to - write a post. Clicking "post" will make a Micropub request to your endpoint.

- - - -

Configuring Endpoints

- -

Authorization Endpoint

- - -

Token Endpoint

- - -

Micropub Endpoint

- - -

The Creating a Micropub Endpoint tutorial will walk you through how to handle incoming POST requests from apps like this.

- - - -

Syndication Targets

- -

You can provide a list of supported syndication targets that will appear as checkboxes when you are creating a new post.

- -

To do this, your Micropub endpoint will need to respond to a GET request containing a query string of q=syndicate-to. This request will be made with the access token that was generated for this app, so you can choose which syndication targets you want to allow this app to use.

- -

Below is the request and expected response that Quill looks for.

- - 
GET /micropub?q=syndicate-to HTTP/1.1
-Authorization: Bearer xxxxxxxxxx
-
-HTTP/1.1 200 OK
-Content-type: application/json
-
-{
-  "syndicate-to": [
-    {
-      "uid": "https://twitter.com/aaronpk",
-      "name": "twitter.com/aaronpk"
-    },
-    {
-      "uid": "https://news.indieweb.org/en",
-      "name": "IndieNews"
-    }
-  ]
-}
-
- -

The specific values of names and uids are up to your Micropub endpoint, but a good convention is to use the domain name of the service (e.g. https://twitter.com), or domain name and username (e.g. https://twitter.com/aaronpk) for the uid, and a friendly name like "Twitter" or "twitter.com/aaronpk" as the name.

- -

Quill will check for your supported syndication targets when you sign in, but there is also a link on the new post screen to manually re-check if you'd like.

- -
diff --git a/views/docs/creating-posts.php b/views/docs/creating-posts.php new file mode 100644 index 0000000..ca19f48 --- /dev/null +++ b/views/docs/creating-posts.php @@ -0,0 +1,15 @@ +
+ + +

Creating Posts

+ +

Each posting interface in Quill is optimized for a different kind of post. There is an HTML-based editor for writing blog posts with a title and formatted content, a simple note interface, events, bookmarks, travel posts, reviews and more.

+

Each interface will make a Micropub request with different properties to your endpoint. The links below describe the specific properties sent by each posting interface.

+ + + +
diff --git a/views/docs/editor.php b/views/docs/editor.php new file mode 100644 index 0000000..23d2058 --- /dev/null +++ b/views/docs/editor.php @@ -0,0 +1,46 @@ +
+ + +

Rich Editor

+ + + +

The rich editor allows you to write posts with some basic formatting and embedded images.

+ +

Embedded Images

+ +

When editing, you can add images to your post in the interface. There are two ways embedded images are handled.

+ +

If your Micropub server supports a Media Endpoint, then at the time you add the image to the interface, Quill uploads the file to your Media Endpoint and embeds it in the editor as an <img> tag pointing to the file on your server. When you publish the post, the HTML will contain this img tag.

+ + 
+    '); ?>
+
+ +

If your Micropub server does not support a Media Endpoint, then when you add an image in the editor, the image is converted to a data URI, and will be sent to your Micropub endpoint when you publish the post. You don't need to do anything special to handle the image, since if you render this HTML directly, your viewers will see the image! Of course this means your HTML file will increase by the size of the image, so you may wish to implement a Media Endpoint in order to handle images in your posts separately.

+ + 
+    
+
+ +

Post Properties

+ +

The following properties will be sent in the Micropub request. This request will be sent as a standard form-encoded request.

+ +

The access token is sent in the Authorization HTTP header:

+ 
Authorization: Bearer XXXXXXXXX
+ + + +
+ +

Back to Creating Posts

+ +
diff --git a/views/docs/index.php b/views/docs/index.php new file mode 100644 index 0000000..2054a62 --- /dev/null +++ b/views/docs/index.php @@ -0,0 +1,29 @@ +
+ + +

Introduction

+ +
+ +
+ +

Quill is a simple Micropub client for + creating posts on your own website. To use it, your website will need to have + a Micropub endpoint, and this app will send requests to it to create posts.

+ +

There are Micropub plugins for various content management systems such as + Wordpress, and is supported + natively by some software such as Known. + It's also a relatively simple protocol you can implement if you are building + your own website.

+ +

Once you've signed in, you'll be able to use the various interfaces see an interface like the one shown which you can use to + write a post. Clicking "post" will make a Micropub request to your endpoint.

+ +

+ +
diff --git a/views/docs/note.php b/views/docs/note.php new file mode 100644 index 0000000..654c478 --- /dev/null +++ b/views/docs/note.php @@ -0,0 +1,40 @@ +
+ + +

Note

+ + + +

The note interface is for creating simple text posts and optionally adding images.

+ +

Adding Photos

+ +

If your Micropub server supports a Media Endpoint, then at the time you select a photo, Quill uploads the file to your Media Endpoint and shows a preview in the interface. The image URL will be sent as a string in the request.

+ +

If your Micropub server does not support a Media Endpoint, then when you add an image, it is not uploaded until you click "post", and then is sent to your Micropub endpoint as a file.

+ +

Post Properties

+ +

The following properties will be sent in the Micropub request. This request will be sent as either a form-encoded or a multipart-encoded request, depending on whether there are photos and whether you have a Media Endpoint.

+ +

If you have a Media Endpoint, then you'll always get a form-encoded request with the URL of any photos. If you do not have a Media Endpoint, and if there is a photo, you'll get a multipart request so that photos are uploaded directly to your Micropub endpoint.

+ +

The access token is sent in the Authorization HTTP header:

+ 
Authorization: Bearer XXXXXXXXX
+ + + +
+ +

Back to Creating Posts

+ +
diff --git a/views/docs/post-status.php b/views/docs/post-status.php new file mode 100644 index 0000000..dd08aa7 --- /dev/null +++ b/views/docs/post-status.php @@ -0,0 +1,10 @@ +
+ + +

Post Status

+ +

The "Post Status" dropdown in the Quill editor is just an indication to your Micropub endpoint to mark the post as "published" or "draft". If your Micropub endpoint does not support this property, then your post will be published immediately.

+ +

Setting the dropdown to "draft" will include a new property in the Micropub request, called post-status with the value set to draft. You can read more about this extension on the IndieWeb wiki.

+ +
\ No newline at end of file diff --git a/views/docs/signing-in.php b/views/docs/signing-in.php new file mode 100644 index 0000000..487192f --- /dev/null +++ b/views/docs/signing-in.php @@ -0,0 +1,37 @@ +
+ + +

Signing In

+ +

To begin using Quill, you need to sign in. This will grant Quill an access token that it + will use when it creates posts on your website.

+ +

Authentication happens at a website that you choose, and you authorize Quill to be able + to post on your website. If you are familiar with OAuth 2.0, you will recognize many + of the concepts here.

+ +

When you sign in to Quill, you start by entering your URL. This URL delegates the various + aspects of signing in and granting authorization to other services, which may or may + not be part of your website.

+ +

Configuring Endpoints

+ +

To tell Quill where to find the endpoints it will need to log you in, you'll need + to add some HTML tags to your home page.

+ +

Authorization Endpoint

+ + +

Token Endpoint

+ + +

Micropub Endpoint

+ + +

The Creating a Micropub Endpoint tutorial will walk you through how to handle incoming POST requests from apps like this.

+ +
+ +

Continue to Creating Posts

+ +
diff --git a/views/docs/syndication.php b/views/docs/syndication.php new file mode 100644 index 0000000..3452173 --- /dev/null +++ b/views/docs/syndication.php @@ -0,0 +1,38 @@ +
+ + +

Syndication Targets

+ +

You can provide a list of supported syndication targets that will appear as checkboxes when you are creating a new post.

+ +

To do this, your Micropub endpoint will need to respond to a GET request containing a query string of q=syndicate-to. This request will be made with the access token that was generated for this app, so you can choose which syndication targets you want to allow this app to use.

+ +

Below is the request and expected response that Quill looks for.

+ + 
GET /micropub?q=syndicate-to HTTP/1.1
+Authorization: Bearer xxxxxxxxxx
+
+HTTP/1.1 200 OK
+Content-type: application/json
+
+{
+  "syndicate-to": [
+    {
+      "uid": "https://twitter.com/aaronpk",
+      "name": "twitter.com/aaronpk"
+    },
+    {
+      "uid": "https://news.indieweb.org/en",
+      "name": "IndieNews"
+    }
+  ]
+}
+
+ +

The specific values of names and uids are up to your Micropub endpoint, but a good convention is to use the domain name of the service (e.g. https://twitter.com), or domain name and username (e.g. https://twitter.com/aaronpk) for the uid, and a friendly name like "Twitter" or "twitter.com/aaronpk" as the name.

+ +

Quill will check for your supported syndication targets when you sign in, but there is also a link on the new post screen to manually re-check if you'd like.

+ +

When you create a post and tap one of the syndication options, the value of uid is sent in a property called mp-syndicate-to, which instructs your endpoint to syndicate to that target. Note that Quill doesn't know whether the target is Twitter, Facebook, or something else, and doesn't talk to the service directly. It's just an instruction to your endpoint to syndicate to that destination.

+ +
-- cgit v1.2.3