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

DOCS Rework documentation to have clear user guide and dev docs.
This commit is contained in:
Damian Mooyman 2016-01-08 12:54:55 +13:00
commit 340ff3e737
29 changed files with 138 additions and 56 deletions

View File

@ -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) [![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) [Developer documentation](docs/en/index.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)
## Requirements ## 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. 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
```

View File

@ -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
```

View File

@ -1,9 +1,4 @@
# Pagination # Configuring 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)
To customise the look and feel of the pagination component, simply override the template located at `/blog/templates/Includes/Pagination.ss` 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). 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).

View File

@ -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.

11
docs/en/index.md Normal file
View File

@ -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)

View File

@ -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.

View File

Before

Width:  |  Height:  |  Size: 98 KiB

After

Width:  |  Height:  |  Size: 98 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 64 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 83 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 44 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 44 KiB

View File

Before

Width:  |  Height:  |  Size: 7.1 KiB

After

Width:  |  Height:  |  Size: 7.1 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 89 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 88 KiB

View File

Before

Width:  |  Height:  |  Size: 26 KiB

After

Width:  |  Height:  |  Size: 26 KiB

View File

Before

Width:  |  Height:  |  Size: 18 KiB

After

Width:  |  Height:  |  Size: 18 KiB

View File

Before

Width:  |  Height:  |  Size: 16 KiB

After

Width:  |  Height:  |  Size: 16 KiB

View File

Before

Width:  |  Height:  |  Size: 18 KiB

After

Width:  |  Height:  |  Size: 18 KiB

View File

Before

Width:  |  Height:  |  Size: 13 KiB

After

Width:  |  Height:  |  Size: 13 KiB

View File

Before

Width:  |  Height:  |  Size: 82 KiB

After

Width:  |  Height:  |  Size: 82 KiB

View File

@ -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)

View File

@ -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)

View File

@ -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)

View File

@ -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)

View File

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

View File

@ -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. **This guide assumes you have the optional [Widgets](https://addons.silverstripe.org/add-ons/silverstripe/widgets/) module 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.
![](_images/widgets.png) ![](_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. 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. The archive widget helps you keep historical content relevant, by generating a list of posts, ordered by month or year.
![](_images/widgets-archive.png) ![](_images/widgets-archive.png)
## Blog Categories ### Blog Categories
The blog categories widget lets your readers easily find the content they're interested in. The blog categories widget lets your readers easily find the content they're interested in.
![](_images/widgets-categories.png) ![](_images/widgets-categories.png)
## Recent Posts ### Recent Posts
The recent posts widget is great for providing quick links to your latest content. The recent posts widget is great for providing quick links to your latest content.
![](_images/widgets-recent-posts.png) ![](_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. Similar to the blog categories widget, blog tags help your readers find relevant content, at more fine grained level.
![](_images/widgets-tags.png) ![](_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)