Skip to content

Commit 6ab6d6d

Browse files
ditschedevditschedev
committed
📑 Updated documentation in README.md
1 parent 418ceaf commit 6ab6d6d

File tree

1 file changed

+146
-25
lines changed

1 file changed

+146
-25
lines changed

‎README.md‎

Lines changed: 146 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -4,32 +4,169 @@
44
![npm downloads](https://img.shields.io/npm/dw/nuxtjs-ghost)
55
![License](https://img.shields.io/github/license/ditschedev/nuxtjs-ghost)
66

7-
> {{ description }}
7+
> NuxtJS module to easily interact with the Ghost API
88
99
[📖 **Release Notes**](./CHANGELOG.md)
1010

1111
## Setup
1212

13-
1. Add `{{ name }}` dependency to your project
13+
To start using the module you first need to install it using the package manager of your choice.
14+
15+
Installation with yarn
16+
17+
```bash
18+
yarn add nuxtjs-ghost
19+
```
20+
21+
Installation with npm
1422

1523
```bash
16-
yarn add {{ name }} # or npm install {{ name }}
24+
npm install nuxtjs-ghost
1725
```
1826

19-
2. Add `{{ name }}` to the `modules` section of `nuxt.config.js`
27+
After that you need to register the plugin, that NuxtJS can pick it up. To do this, add `nuxtjs-ghost` to your `modules` section of `nuxt.config.js`.
2028

2129
```js
2230
{
2331
modules: [
24-
// Simple usage
25-
'{{ name }}',
32+
'nuxtjs-ghost',
33+
]
34+
}
35+
```
2636

27-
// With options
28-
['{{ name }}', { /* module options */ }]
37+
## Configuration
38+
The plugin needs an api key of your site and its endpoint url. Optionally you can pass the version of the Ghost API you want to use. Typically the endpoint for your api is your sites hostname.
39+
40+
To set these values you have two options:
41+
1. Use the default module options
42+
2. Add your options globally to the `nuxt.config.js`
43+
44+
#### Module Options
45+
When registering the module, don't register it as a string, but an array. The syntax should be:
46+
```js
47+
{
48+
modules: [
49+
[
50+
'nuxtjs-ghost',
51+
{
52+
url: 'YOUR_API_ENDPOINT',
53+
key: 'YOUR_API_KEY'
54+
}
55+
]
2956
]
3057
}
3158
```
3259

60+
#### Global Configuration
61+
To set up global configuration, add the following object to your `export` of `nuxt.config.js`:
62+
```js
63+
ghost: {
64+
url: 'YOUR_API_ENDPOINT',
65+
key: 'YOUR_API_KEY'
66+
}
67+
```
68+
69+
## Usage
70+
The usage is pretty straight forward. This package is just a wrapper for the official [JavaScript Content API](https://ghost.org/docs/api/v3/content/). Please check out their documentation to learn about [filtering](https://ghost.org/docs/api/v3/content/#parameters) or [pagination](https://ghost.org/docs/api/v3/content/#pagination). The `filter` parameter of the following methods is an `object` representation of the available query filters.
71+
72+
To access the wrapper it is getting exposed to the application context as `$ghost`. Use it in your pages `created()`, or `mounted()` functions using `this`.
73+
```js
74+
export default {
75+
async created() {
76+
const posts = await this.$ghost.getPosts()
77+
}
78+
}
79+
```
80+
Or use it in SSR-mode inside of `asyncData()`
81+
```js
82+
export default {
83+
async asyncData({ $ghost }) {
84+
const posts = await $ghost.getPosts()
85+
return {
86+
posts
87+
}
88+
}
89+
}
90+
```
91+
92+
All available methods are documented below:
93+
94+
-----
95+
96+
#### `async getPosts(filter)` - Gets all posts matching the filter query.
97+
**Parameters**:
98+
- (optional) `filter`: Object used for filtering. E.g.: `{limit: 2, include: 'tags,authors'}`
99+
100+
**Returns**: An `array` of posts
101+
102+
-----
103+
104+
#### `async getPost(query, filter)` - Gets the post matching the identifier given in `query`.
105+
**Parameters**:
106+
- `query`: Object giving the identifier of the post. Can be `slug` or `id`. E.g.: `{slug: 'my-post'}`
107+
- (optional) `filter`: Object used for filtering. E.g.: `{formats: ['html', 'plaintext']}}`
108+
109+
**Returns**: An `object` representing a post
110+
111+
-----
112+
113+
#### `async getAuthors(filter)` - Gets all authors matching the filter query.
114+
**Parameters**:
115+
- (optional) `filter`: Object used for filtering. E.g.: `{include: 'count.posts'}`
116+
117+
**Returns**: An `array` of authors
118+
119+
-----
120+
121+
#### `async getAuthor(query, filter)` - Gets the author matching the identifier given in `query`.
122+
**Parameters**:
123+
- `query`: Object giving the identifier of the author. Can be `slug` or `id`. E.g.: `{id: '1234'}`
124+
- (optional) `filter`: Object used for filtering. E.g.: `{page: 2}`
125+
126+
**Returns**: An `object` representing an author
127+
128+
-----
129+
130+
#### `async getTags(filter)` - Gets all tags matching the filter query.
131+
**Parameters**:
132+
- (optional) `filter`: Object used for filtering. E.g.: `{include: 'count.posts'}`
133+
134+
**Returns**: An `array` of tags
135+
136+
-----
137+
138+
#### `async getTag(query, filter)` - Gets the tag matching the identifier given in `query`.
139+
**Parameters**:
140+
- `query`: Object giving the identifier of the tag. Can be `slug` or `id`. E.g.: `{id: '1234'}`
141+
- (optional) `filter`: Object used for filtering. E.g.: `{include: 'count.posts'}`
142+
143+
**Returns**: An `object` representing a tag
144+
145+
-----
146+
147+
#### `async getPages(filter)` - Gets all pages matching the filter query.
148+
**Parameters**:
149+
- (optional) `filter`: Object used for filtering. E.g.: `{limit: 2}`
150+
151+
**Returns**: An `array` of pages
152+
153+
-----
154+
155+
#### `async getTag(query, filter)` - Gets the page matching the identifier given in `query`.
156+
**Parameters**:
157+
- `query`: Object giving the identifier of the page. Can be `slug` or `id`. E.g.: `{id: '1234'}`
158+
- (optional) `filter`: Object used for filtering. E.g.: `{fields: ['title']}`
159+
160+
**Returns**: An `object` representing a page
161+
162+
-----
163+
164+
#### `async getSettings()` - Gets your sites settings.
165+
166+
**Returns**: An `object` representing your settings
167+
168+
-----
169+
33170
## Development
34171

35172
1. Clone this repository
@@ -40,20 +177,4 @@ yarn add {{ name }} # or npm install {{ name }}
40177

41178
[MIT License](./LICENSE)
42179

43-
Copyright (c) {{ author }}
44-
45-
<!-- Badges -->
46-
[npm-version-src]: https://img.shields.io/npm/v/{{ name }}/latest.svg
47-
[npm-version-href]: https://npmjs.com/package/{{ name }}
48-
49-
[npm-downloads-src]: https://img.shields.io/npm/dt/{{ name }}.svg
50-
[npm-downloads-href]: https://npmjs.com/package/{{ name }}
51-
52-
[github-actions-ci-src]: https://github.com/{{ github }}/workflows/ci/badge.svg
53-
[github-actions-ci-href]: https://github.com/{{ github }}/actions?query=workflow%3Aci
54-
55-
[codecov-src]: https://img.shields.io/codecov/c/github/{{ github }}.svg
56-
[codecov-href]: https://codecov.io/gh/{{ github }}
57-
58-
[license-src]: https://img.shields.io/npm/l/{{ name }}.svg
59-
[license-href]: https://npmjs.com/package/{{ name }}
180+
Copyright (c) Tobias Dittmann

0 commit comments

Comments
 (0)