Merge pull request #349 from camfindlay/feature/docs-userguide

DOCS Rework documentation to have clear user guide and dev docs.

README.md

@@ -2,15 +2,10 @@
 
 [![Build Status](https://travis-ci.org/silverstripe/silverstripe-blog.png?branch=master)](https://travis-ci.org/silverstripe/silverstripe-blog) [![Latest Stable Version](https://poser.pugx.org/silverstripe/blog/v/stable.svg)](https://packagist.org/packages/silverstripe/blog) [![Total Downloads](https://poser.pugx.org/silverstripe/blog/downloads.svg)](https://packagist.org/packages/silverstripe/blog) [![Latest Unstable Version](https://poser.pugx.org/silverstripe/blog/v/unstable.svg)](https://packagist.org/silverstripe/silverstripe/blog) [![License](https://poser.pugx.org/silverstripe/blog/license.svg)](https://packagist.org/packages/silverstripe/blog)
 
-## Features
+## Documentation
+[User guide](docs/en/userguide/index.md)
 
-* [User roles](docs/en/roles.md)
-* [Tags and categories](docs/en/tags-and-categories.md)
-* [Custom publish dates](docs/en/custom-publish-dates.md)
-* [RSS Feed](docs/en/rss-feed.md)
-* [Widgets](docs/en/widgets.md) (optional)
-* [Custom pagination](docs/en/pagination.md)
-* [Minimal design reduces SiteTree clutter](#usage)
+[Developer documentation](docs/en/index.md)
 
 ## Requirements
 
@@ -37,19 +32,4 @@ composer require silverstripe/blog 2.0.x-dev
 
 If you're upgrading from blog version 1.0 to 2.0 you will need to run the `BlogMigrationTask`. Run the task using `dev/tasks/BlogMigrationTask` either via the browser or sake CLI to migrate your legacy blog to the new version data structure.
 
-## Usage
 
-Because your blog is part of the SiteTree, usage is the same as any other page.
-
-By default, blog posts don't appear in the SiteTree, to avoid clutter. Instead they appear inside your blog as a GridField.
-
-![](docs/en/_images/blog-post-management.png)
-
-If you'd rather display your posts within the SiteTree, you can do so using SilverStripe config.
-
-In mysite/_config/settings.yml
-
-```yaml
-BlogPost:
-  show_in_sitetree: true
-```

docs/en/configuring-blog-posts.md

@@ -0,0 +1,16 @@
+## Configuring blog posts in SiteTree
+
+Because your blog is part of the SiteTree, usage is the same as any other page.
+
+By default, blog posts don't appear in the SiteTree, to avoid clutter. Instead they appear inside your blog as a GridField.
+
+![](_images/blog-post-management.png)
+
+If you'd rather display your posts within the SiteTree, you can do so using SilverStripe config.
+
+In mysite/_config/settings.yml
+
+```yaml
+BlogPost:
+  show_in_sitetree: true
+```

docs/en/configuring-pagination.md

@@ -1,9 +1,4 @@
-# Pagination
-
-By default your Blog will display ten posts per page. The number of posts per page is configurable via the "Settings" tab. Setting posts per page to zero will disable pagination, displaying all of your posts on a single page.
-
-![](_images/blog-settings-pagination.png)
-
+# Configuring pagination
 To customise the look and feel of the pagination component, simply override the template located at `/blog/templates/Includes/Pagination.ss`
 
 If you have comments enabled, comment pagination is configurable via the [SilverStripe Comments Module configuration](https://github.com/silverstripe/silverstripe-comments/blob/master/docs/en/Configuration.md).

docs/en/configuring-widgets.md

@@ -0,0 +1,16 @@
+# Configuring Widgets
+
+The blog module comes bundled with some useful widgets. To take advantage of them, you'll need to install the [SilverStripe widgets module](https://github.com/silverstripe/silverstripe-widgets). Widgets are totally optional - so your blog will work just fine without having widgets installed.
+
+You can enable the widgets by adding the following YML config:
+
+```yaml
+Blog:
+  extensions:
+    - WidgetPageExtension
+BlogPost:
+  extensions:
+    - WidgetPageExtension
+```
+
+Once you have widgets installed you'll see the "Widgets" tab in the content section of your blog.

docs/en/index.md

@@ -0,0 +1,11 @@
+# Blog documentation
+
+## Development
+ * [Configuring blog posts in Sitetree](configuring-blog-posts.md)
+ * [Configuring blog when on large websites](configuring-large-websites.md)
+ * [Configuring widgets](configuring-widgets.md)
+ * [Configuring pagination](configuring-pagination.md)
+
+## CMS user help
+ * [User guide](userguide/index.md)
+ 

docs/en/tags-and-categories.md

@@ -1,7 +0,0 @@
-# Tags and categories
-
-Quickly add new tags and categories to your posts.
-
-![](_images/blogpost-add-tags-categories.png)
-
-We use the [SilverStripe TagField module](https://github.com/silverstripe-labs/silverstripe-tagfield) to allow easy management of tags and categories, on the fly.

docs/en/userguide/adding-blog-posts.md

@@ -0,0 +1,30 @@
+title: Adding a blog post
+summary: How to add a new blog post.
+
+# Adding a blog post
+
+## Creating a new blog
+
+On the top of the Contents pane, you will find a button marked "Create."  Click it, and a drop-down menu will show up. Select "Blog", then hit the "Go" button.
+
+You will notice that a new blog page has been created, with the name of "New Blog". Rename this to "Blog" (or whatever you wish to call this page) and then you can later reorder where this is in your website tree.
+
+Click on the new blog page to start creating posts.
+
+![Adding a blog](_images/blogging-add-blog.png)
+
+## Creating a blog post
+
+To create a blog post, click on your Blog page in the Page Tree in the site-tree Pane. You will see a list of past blog posts and a green button reading "Add new Blog Post", click this to add a new post.
+
+![Adding a blog post](_images/blogging-add-blog-post.png)
+
+Fill out your blog post content as you would any page in the CMS. 
+
+You can also include a banner images and a custom summary description (if this is omitted the first 15 words of your post content will be used when displaying your posts's abstract).
+
+![Banner image and summary](_images/blogging-banner-summary.png)
+
+There is a new right hand panel where you can set a publish date, categories, tags and authors.
+
+![Setting blog options](_images/blogging-options.png)

docs/en/userguide/index.md

@@ -0,0 +1,19 @@
+title: Blogging
+summary: Working with blogging and comments in SilverStripe CMS.
+
+# Blogging in SilverStripe CMS
+
+## Before we begin
+
+Make sure that your SilverStripe CMS installation has the [Blog](https://addons.silverstripe.org/add-ons/silverstripe/blog/) module and optional, [Widgets](https://addons.silverstripe.org/add-ons/silverstripe/widgets/) and [Comments](https://addons.silverstripe.org/add-ons/silverstripe/comments/) modules installed.
+
+## Blogging features
+
+ * [Adding blog posts](adding-blog-posts.md)
+ * [Custom publishing dates](custom-publish-dates.md)
+ * [Pagination](pagination.md)
+ * [Roles](roles.md)
+ * [RSS Feed](rss-feed.md)
+ * [Tags and categories](tags-and-categories.md)
+ * [Using widgets](using-widgets.md)
+ * [Managing comments](managing-comments.md)

docs/en/userguide/managing-comments.md

@@ -0,0 +1,15 @@
+# Managing comments
+
+**This guide assumes you have the optional [Comments](https://addons.silverstripe.org/add-ons/silverstripe/comments/) module installed**
+
+If comments have been enabled on your website you will be able to moderate comments. You can access all comments through the left navigation 
+item title "Comments" or on a per blog post basis in the "Comments" tab when editing a blog post. 
+
+![Comments interface](_images/comments.png)
+
+As new comments are made they show in the "New" tab. From here you can opt to approve comments or mark a comment as spam.
+
+![Comments marking as spam](_images/comments-spam.png)
+
+
+ 

docs/en/userguide/pagination.md

@@ -0,0 +1,5 @@
+# Pagination
+
+By default your Blog will display ten posts per page. The number of posts per page is configurable via the "Settings" tab. Setting posts per page to zero will disable pagination, displaying all of your posts on a single page.
+
+![](_images/blog-settings-pagination.png)

docs/en/userguide/tags-and-categories.md

@@ -0,0 +1,5 @@
+# Tags and categories
+
+Quickly add new tags and categories to your posts.
+
+![](_images/blogpost-add-tags-categories.png)

docs/en/userguide/using-widgets.md

@@ -1,20 +1,6 @@
-# Widgets
+# Using Widgets
 
-The blog module comes bundled with some useful widgets. To take advantage of them, you'll need to install the [SilverStripe widgets module](https://github.com/silverstripe/silverstripe-widgets). Widgets are totally optional - so your blog will work just fine without having widgets installed.
-
-You can enable the widgets by adding the following YML config:
-
-```yml
-Blog:
-  extensions:
-    - WidgetPageExtension
-
-BlogPost:
-  extensions:
-    - WidgetPageExtension
-```
-
-Once you have widgets installed you'll see the "Widgets" tab in the content section of your blog.
+**This guide assumes you have the optional [Widgets](https://addons.silverstripe.org/add-ons/silverstripe/widgets/) module installed**
 
 ![](_images/widgets.png)
 
@@ -22,26 +8,37 @@ To add a widget - simply click the *plus* icon and the widget will be appear in
 
 After you've finished adding widgets, publish your blog, and your freshly minted widgets will appear in your blog's sidebar.
 
-## Archive
+## Available blog widgets
+
+### Archive
 
 The archive widget helps you keep historical content relevant, by generating a list of posts, ordered by month or year.
 
 ![](_images/widgets-archive.png)
 
-## Blog Categories
+### Blog Categories
 
 The blog categories widget lets your readers easily find the content they're interested in.
 
 ![](_images/widgets-categories.png)
 
-## Recent Posts
+### Recent Posts
 
 The recent posts widget is great for providing quick links to your latest content.
 
 ![](_images/widgets-recent-posts.png)
 
-## Blog Tags
+### Blog Tags
 
 Similar to the blog categories widget, blog tags help your readers find relevant content, at more fine grained level.
 
 ![](_images/widgets-tags.png)
+
+## Optional extra widgets
+
+Additional widgets can be installed alongside your blog. 
+
+ * [Content Widget - Display HTML content in a widget](https://github.com/silverstripe-labs/silverstripe-content-widget)
+
+
+