diff --git a/README.md b/README.md index d83d9af..9d6ad6c 100755 --- a/README.md +++ b/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 -``` diff --git a/docs/en/configuring-blog-posts.md b/docs/en/configuring-blog-posts.md new file mode 100644 index 0000000..01c4cb9 --- /dev/null +++ b/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 +``` \ No newline at end of file diff --git a/docs/en/pagination.md b/docs/en/configuring-pagination.md similarity index 55% rename from docs/en/pagination.md rename to docs/en/configuring-pagination.md index f54c73b..4c021e6 100644 --- a/docs/en/pagination.md +++ b/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). \ No newline at end of file diff --git a/docs/en/configuring-widgets.md b/docs/en/configuring-widgets.md new file mode 100644 index 0000000..f52727f --- /dev/null +++ b/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. diff --git a/docs/en/index.md b/docs/en/index.md new file mode 100644 index 0000000..14460ad --- /dev/null +++ b/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) + diff --git a/docs/en/tags-and-categories.md b/docs/en/tags-and-categories.md deleted file mode 100644 index 3d5456d..0000000 --- a/docs/en/tags-and-categories.md +++ /dev/null @@ -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. diff --git a/docs/en/_images/blog-settings-pagination.png b/docs/en/userguide/_images/blog-settings-pagination.png similarity index 100% rename from docs/en/_images/blog-settings-pagination.png rename to docs/en/userguide/_images/blog-settings-pagination.png diff --git a/docs/en/userguide/_images/blogging-add-blog-post.png b/docs/en/userguide/_images/blogging-add-blog-post.png new file mode 100644 index 0000000..7105e74 Binary files /dev/null and b/docs/en/userguide/_images/blogging-add-blog-post.png differ diff --git a/docs/en/userguide/_images/blogging-add-blog.png b/docs/en/userguide/_images/blogging-add-blog.png new file mode 100644 index 0000000..584420d Binary files /dev/null and b/docs/en/userguide/_images/blogging-add-blog.png differ diff --git a/docs/en/userguide/_images/blogging-banner-summary.png b/docs/en/userguide/_images/blogging-banner-summary.png new file mode 100644 index 0000000..9272b17 Binary files /dev/null and b/docs/en/userguide/_images/blogging-banner-summary.png differ diff --git a/docs/en/userguide/_images/blogging-options.png b/docs/en/userguide/_images/blogging-options.png new file mode 100644 index 0000000..30a97eb Binary files /dev/null and b/docs/en/userguide/_images/blogging-options.png differ diff --git a/docs/en/_images/blogpost-add-tags-categories.png b/docs/en/userguide/_images/blogpost-add-tags-categories.png similarity index 100% rename from docs/en/_images/blogpost-add-tags-categories.png rename to docs/en/userguide/_images/blogpost-add-tags-categories.png diff --git a/docs/en/userguide/_images/comments-spam.png b/docs/en/userguide/_images/comments-spam.png new file mode 100644 index 0000000..188ddaa Binary files /dev/null and b/docs/en/userguide/_images/comments-spam.png differ diff --git a/docs/en/userguide/_images/comments.png b/docs/en/userguide/_images/comments.png new file mode 100644 index 0000000..896a59b Binary files /dev/null and b/docs/en/userguide/_images/comments.png differ diff --git a/docs/en/_images/post-publish-date.png b/docs/en/userguide/_images/post-publish-date.png similarity index 100% rename from docs/en/_images/post-publish-date.png rename to docs/en/userguide/_images/post-publish-date.png diff --git a/docs/en/_images/widgets-archive.png b/docs/en/userguide/_images/widgets-archive.png similarity index 100% rename from docs/en/_images/widgets-archive.png rename to docs/en/userguide/_images/widgets-archive.png diff --git a/docs/en/_images/widgets-categories.png b/docs/en/userguide/_images/widgets-categories.png similarity index 100% rename from docs/en/_images/widgets-categories.png rename to docs/en/userguide/_images/widgets-categories.png diff --git a/docs/en/_images/widgets-recent-posts.png b/docs/en/userguide/_images/widgets-recent-posts.png similarity index 100% rename from docs/en/_images/widgets-recent-posts.png rename to docs/en/userguide/_images/widgets-recent-posts.png diff --git a/docs/en/_images/widgets-tags.png b/docs/en/userguide/_images/widgets-tags.png similarity index 100% rename from docs/en/_images/widgets-tags.png rename to docs/en/userguide/_images/widgets-tags.png diff --git a/docs/en/_images/widgets.png b/docs/en/userguide/_images/widgets.png similarity index 100% rename from docs/en/_images/widgets.png rename to docs/en/userguide/_images/widgets.png diff --git a/docs/en/userguide/adding-blog-posts.md b/docs/en/userguide/adding-blog-posts.md new file mode 100644 index 0000000..0e033c4 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/en/custom-publish-dates.md b/docs/en/userguide/custom-publish-dates.md similarity index 100% rename from docs/en/custom-publish-dates.md rename to docs/en/userguide/custom-publish-dates.md diff --git a/docs/en/userguide/index.md b/docs/en/userguide/index.md new file mode 100644 index 0000000..7932a2e --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/en/userguide/managing-comments.md b/docs/en/userguide/managing-comments.md new file mode 100644 index 0000000..4271044 --- /dev/null +++ b/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) + + + \ No newline at end of file diff --git a/docs/en/userguide/pagination.md b/docs/en/userguide/pagination.md new file mode 100644 index 0000000..e8d45c6 --- /dev/null +++ b/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) diff --git a/docs/en/roles.md b/docs/en/userguide/roles.md similarity index 100% rename from docs/en/roles.md rename to docs/en/userguide/roles.md diff --git a/docs/en/rss-feed.md b/docs/en/userguide/rss-feed.md similarity index 100% rename from docs/en/rss-feed.md rename to docs/en/userguide/rss-feed.md diff --git a/docs/en/userguide/tags-and-categories.md b/docs/en/userguide/tags-and-categories.md new file mode 100644 index 0000000..b2a22c4 --- /dev/null +++ b/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) diff --git a/docs/en/widgets.md b/docs/en/userguide/using-widgets.md similarity index 57% rename from docs/en/widgets.md rename to docs/en/userguide/using-widgets.md index 4d77c39..46124b0 100644 --- a/docs/en/widgets.md +++ b/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) + + +