@akashacms/plugins-authors/guide/index.html.md

A plugin for AkashaCMS to support acknowledging authors

---
layout: plugin-documentation.html.ejs
title: AskashaCMS Author plugin documentation
publicationDate: August 9, 2019
---

We often want an article to include author attribution.  For example a blog post, news article, etc, is more relevant if the reader knows the authors name and has a link to a bio.

With this plugin the `config.js` file holds a list of authors, and each content document can declare one or more authors.  Custom elements are available to present a list of one or more authors like:

```
By <a href="URL">Boy George</a>, <a href="URL">Elton John</a>
```

Additionally the default template contains appropriate `Schema.org` metadata, and any link will contain a `rel=author` attribute.

# Installation

Add the following to `package.json`

```json
"dependencies": {
    ...
    "@akashacms/plugins-author": "^0.9.x"
    ...
}
```

Once added to `package.json` run: `npm install`


# Configuration

Add the following to `config.js` 

```
config
    ...
    .use(require('@akashacms/plugin-author'), {
        default: "boygeorge",
        authors: [
            {
                code: "boygeorge",
                fullname: "Boy George",
                url: "URL",
                bio: "<p>Weird ass british rocker</p>"
            },
            {
                code: "eltonjohn",
                fullname: "Elton John",
                url: "URL",
                bio: "<p>Mainstream british rocker</p>"
            }
        ]
    })
    ...
```

If your config file is in ESM format, it is called `config.mjs` and the plugin is handled this way:

```js
// ...
import { AuthorsPlugin } from '@akashacms/plugins-authors';
// ...
config.
    // ...

    .use(AuthorsPlugin, {
        default: "boygeorge",
        authors: [
            {
                code: "boygeorge",
                fullname: "Boy George",
                url: "Boy-George-URL",
                bio: "<p>Weird ass british rocker</p>"
            },
            {
                code: "eltonjohn",
                fullname: "Elton John",
                url: "Elton-John-URL",
                bio: "<p>Mainstream british rocker</p>"
            }
        ]
    })
    // ...
```

# Custom Tags

## `authors-byline`

```html
<authors-byline data-authors='[ "authorcode" ]'></author-byline>

OR

<authors-byline data-authors="authorcode"></author-byline>
```

The other attributes are:

* `template="partial-file.html.ejs"` -- Override the default template, `authors-byline.html.ejs`
* `id="ID"` -- An ID attribute for the outer element
* `class="class"` -- Additional class values for the outer element
* `style="style"` -- CSS style attribute

The data provided is:

* `id` - The ID attribute if any (`undefined` otherwise)
* `style` - The style attribute if any (`undefined` otherwise) 
* `additionalClasses` -- Any class value supplied, or `undefined`
* `authors` -- The author objects corresponding to the supplied authorcode(s)

## `authors-bio-block`

```html
<authors-bio-block data-authors="eltonjohn"></authors-bio-block>

OR

<authors-bio-block data-authors='[ "boygeorge", "eltonjohn" ]'></authors-bio-block>
```

The other attributes are:

* `template="partial-file.html.ejs"` -- Override the default template, `authors-bio-block.html.ejs`
* `id="ID"` -- An ID attribute for the outer element
* `class="class"` -- Additional class values for the outer element
* `style="style"` -- CSS style attribute

The data provided is:

* `id` - The ID attribute if any (`undefined` otherwise)
* `style` - The style attribute if any (`undefined` otherwise) 
* `additionalClasses` -- Any class value supplied, or `undefined`
* `authors` -- The author objects corresponding to the supplied authorcode(s)