Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/apostrophecms-legacy/apostrophe-blog-2

A next-generation blog designed to be more contextual. Blogs and blog posts are just ordinary pages with permanent URLs of their own, with a few not-so-ordinary features to accommodate blog-style browsing and aggregation.
https://github.com/apostrophecms-legacy/apostrophe-blog-2

Last synced: 5 days ago
JSON representation

A next-generation blog designed to be more contextual. Blogs and blog posts are just ordinary pages with permanent URLs of their own, with a few not-so-ordinary features to accommodate blog-style browsing and aggregation.

Awesome Lists containing this project

README 

        
## NOT FOR NEW PROJECTS



This module is for the 0.5.x version of Apostrophe. The [apostrophe-blog](https://npmjs.org/apostrophe-blog) module has been updated for Apostrophe 2.x.



Some of the use cases of this module are not yet available as a pre-packaged module for 2.x, however you can recreate them using `apostrophe-custom-pages`, a built-in module of 2.x.



# apostrophe-blog-2: a better blog for Apostrophe



This new implementation is based on the idea that blog posts have more in common with pages than with snippets. It simplifies permissions and makes the whole experience more contextual.



Each blog post is a child of its parent blog. This allows permissions to work just like page permissions in Apostrophe. However, the pagination of posts works as you would expect it to in a post, and the posts don't clutter up the "reorganize" modal.



A blog can still choose to display content from other blogs on the site. This is easy to do via the page settings of the blog (see the "and these blogs" field).



There is also a widget available for displaying blog posts anywhere on the site.



## Configuration Options



Blog posts cannot have subpages. And, by default, index pages can't have subpages other than blog posts. But you can enable the latter by setting the `allowSubpagesOfIndex` option to `true` when configuring the module. It's not forbidden, it's just confusing for users who don't need it.



## Subclassing



For now, subclassing of blog-2 is fairly simple, though it requires some configuration in your app.js file. Here's a sample of what you'll need to successfully subclass and create your own distinct instance of a blog-like thing:



```JavaScript

'handbook': {

    extend: 'apostrophe-blog-2',

    name: 'handbooks',

    pieceName: 'policy',

    pieceLabel: 'Policy',

    indexName: 'handbook',

    indexLabel: 'Handbook',

    pieces: {

      pluralLabel: 'Policies',

    }

  }

```



## Do you like dates in slugs?



By default, the date is part of the slug of each post:



```

/my/blog/2014/11/12/wednesday-update

```



If this doesn't suit your needs, just set the `dateInSlug` option to `false`.



If you are reading this late and already have content with dates, you can remove them:



```

node app apostrophe:remove-dates-from-blog-posts

```



(Note: if you are subclassing, the name of the task depends on your `pieceName` setting. Type `node app apostrophe:help` to list available tasks.)



If you change your mind and want to add dates back, just run:



```

node app apostrophe:add-dates-to-blog-posts

```



Either way, be sure to set the `dateInSlug` option correctly in your module configuration to ensure future posts behave as you expect.



## Limiting Choices in the Widget



Sometimes you won't want the editor to have their pick of title, tag and particular blogs as sources for a particular widget. For instance, you might want to restrict to title only for simplicity.



You can do that with the `sources` option when inserting the widget:



```markup

{{ aposSingleton(page, 'articles', 'blog', { sources: [ 'title' ] }) }}

```



The `sources` option may contain `title`, `tag` and/or `page` in any order. The first option given becomes the default choice.



If you limit the editor to only one source, the dropdown menu is automatically hidden.



## Wordpress Import



You can import content from Wordpress blogs into `apostrophe-blog-2`:



```

node app apostrophe:import-wordpress-stories wordpress-export-file.xml /my-blog

```



The first argument must be a Wordpress XML export file. The second argument must be the slug of an existing blog page on your A2 site.



You can generate a Wordpress export file easily:



1. Log into your wordpress site as an admin.

2. Click "tools."

3. Click "export."

4. Select "posts" or "all." NOTE: only blog posts and associated images and video will be imported. Pages are NOT imported.

5. Save the resulting export file.



### Preserving author credit



The Wordpress import task will migrate in the author's name for each blog post via the `dc:creator` setting found in the XML export file. This field is assigned to the `credit` property of each post in A2. You can add that field to your `pieces` schema as a string field to make it editable on your A2 site.



### Additional options



### Specifying the base URL for relative links



Usually the `wp:base_blog_url` found in the XML export file is good enough to resolve relative URLs to image files if any are encountered in the XML.



However some sites are too tricky with redirects and subdomains for their own good, and you'll need to tell the import task what the real URL of the original Wordpress site is:



`--base=http://magazine.example.com`



#### Ignoring tags



By default Wordpress tags are imported as A2 tags. To prevent this, use the `--ignore-tags` option.



#### Ignoring categories



Wordpress categories are also imported as A2 tags. You can prevent this with the `--ignore-categories` option.



#### Importing only posts with a specific tag



Just use:



`--with-tag="Zamfir Pipes"`



Yes, you may use this option and `--ignore-tags` at the same time.



#### Importing only posts with a specific category



I bet you can guess:



`--with-category="French Press"`



Yes, it is safe to combine this with `--ignore-categories`.



#### Importing only posts that do not have certain tags



`--without-tags="tag1,tag2,tag3"`



Useful if you need to export a "misc" blog with all the content you didn't export to other blogs via `--with-tag`.



This option does not currently work with tags that contain

commas in their names.



#### Importing only posts that do not have certain categories



Useful if you need to export a "misc" blog with all the content you didn't export to other blogs via `--with-category`.



`--without-categories="cat1,cat2,cat3"



This option does not currently work with categories that contain

commas in their names.



#### Changing the body area name



By default, the importer assumes the main content area of your blog posts is named `body`. This might not be the case in your templates. If not, specify `--body-area=content1`, or whatever your area name is.



#### Mapping [caption] shortcodes to descriptions



By default, a [caption] shortcode becomes the title of the file, and the "showTitles" flag is set on the slideshow.



If you prefer it be treated as a description, pass the `--caption-as-description` option.



#### Newline-to-line-break conversion



By default, Wordpress blogs convert double newlines to paragraph breaks. They do it on the fly, all the time, with a hideously complex function. Yes, it's pretty terrible.



By default, during the import, we convert these to a simple pair of `br` tags.



If your particular Wordpress blog has this feature disabled, specify `--no-autop` during import to prevent this conversion, which is redundant for you.



#### Converting creator names



The `dc:creator` setting from Wordpress is normally imported directly into the `credit` field in A2. If you wish, you can specify a CSV file in which the first column is the `dc:creator` value (the Wordpress username) and the second column is the `credit` property to store in A2. Just use:



`--creator-to-credit=filename.csv`



#### Doing it faster



To import the blog faster, processing four blog posts at once, specify `--parallel=4`. Be aware this can require much more memory when importing images. It may also impose an unacceptable load on the Wordpress site at some point. `4` is a good limit, and only on a laptop or a VPS with plenty of memory.