Browse Source

tidying the documentation

master
dgold 3 years ago
parent
commit
7649d0a51b
No known key found for this signature in database GPG Key ID: 6C960885EA9287AD
  1. 92
      INSTALLATION.md
  2. 97
      README.md

92
INSTALLATION.md

@ -4,55 +4,67 @@ Installation
### System Requirements
PHP 7.1+ is required, and the php environment requires php-curl, php-mbstring & php-ctype.
PHP 7.1+ is required, and the php environment requires php-curl, php-mbstring
& php-ctype.
### From Source
Clone the contents of this repository, then copy the `*.php` and the `composer.*` files into your sites **output** folder. If your Static Site Generator wipes the output folder on each run, then there will be some way to make these files be copied on each run -- Hugo, for example, uses the `static` folder.
Clone the contents of this repository, then copy the `*.php` and the
`composer.*` files into your sites **output** folder. If your Static Site
Generator wipes the output folder on each run, then there will be some way to
make these files be copied on each run -- Hugo, for example, uses the `static`
folder.
Since the 1.2 release, nanopub requires the use of [Composer](https://getcomposer.org/). Getting it to do all the things I wanted it to do was getting _way_ beyond my skill level. Install the dependencies with
Since the 1.2 release, nanopub requires the use of
[Composer](https://getcomposer.org/). Getting it to do all the things I wanted
it to do was getting _way_ beyond my skill level. Install the dependencies
with
```
$ composer install
```
If composer complains about outdated dependencies, just ignore that, the dependencies are set in the `composer.lock` file.
If composer complains about outdated dependencies, just ignore that, the
dependencies are set in the `composer.lock` file.
### From .zip
Download the release .zip file from [here](https://github.com/dg01d/nanopub/releases). Unzip, and place the contents in your site's output folder.
Download the release .zip file from
[here](https://github.com/dg01d/nanopub/releases). Unzip, and place the
contents in your site's output folder.
### Configuration
Then edit the included `configs.php` file to enable various features. The full file, including comments is as follows:
Then edit the included `configs.php` file to enable various features. The full
file, including comments is as follows:
```
// First some settings for the site
'siteUrl' => 'https://example.com/', // the URL for your site - note trailing slash
'timezone' => 'Europe/London', // http://php.net/manual/en/timezones.php
'mediaPoint' => 'https://media.org/endpoint', // Micropub Media Endpoin
'tokenPoint' => 'https://tokens.indieauth.com/token', // IndieAuth Token Endpoint
'storageFolder' => '../content', // the folder to store the posts in
'trashFolder' => '../trash', // the folder to move removed posts into
'timezone' => 'Europe/London', // http://php.net/manual/en/timezones.php
'mediaPoint' => 'https://media.org/endpoint', // Micropub Media Endpoin
'tokenPoint' => 'https://tokens.indieauth.com/token', // IndieAuth Token Endpoint
'storageFolder' => '../content', // the folder to store the posts in
'trashFolder' => '../trash', // the folder to move removed posts into
// Config Block for Twitter -- Used only for XRay for rich context replies
'twAPIkey' => 'WomtvR2YoT', // Create an app on dev.twitter.com for your account.
'twAPIsecret' => 'NILIDJXg1e', // APIkey & APIsecret are the APP's key & Secret
'twUserKey' => 'ILs4jUS7a6', // UserKey & User Secret are under 'Your access token'
'twUserSecret' => 'NYbGUfuNUh', // Generate those on dev.twitter.com
'twAPIkey' => 'WomtvR2YoT', // Create an app on dev.twitter.com for your account.
'twAPIsecret' => 'NILIDJXg1e', // APIkey & APIsecret are the APP's key & Secret
'twUserKey' => 'ILs4jUS7a6', // UserKey & User Secret are under 'Your access token'
'twUserSecret' => 'NYbGUfuNUh', // Generate those on dev.twitter.com
// Config Block for Mastodon
'mastodonInstance' => 'servername.ext', // your Mastodon Instance
'mastodonToken' => 'uWo42Bca91', // get an auth code using Mastodon docs
'mastodonToken' => 'uWo42Bca91', // get an auth code using Mastodon docs
// Config for micro.blog
'pingMicro' => True, // Set to False (boolean) if you don't use micro.blog
'siteFeed' => 'https://example.com/atom.xml', // Set to your site's RSS/Atom Feed to notify micro.blog
'pingMicro' => True, // Set to False (boolean) if you don't use micro.blog
'siteFeed' => 'https://example.com/atom.xml', // Set to your site's RSS/Atom Feed to notify micro.blog
// Config for Weather. If you do want weather feature, set to true
// The tracker system that the author has used is Aaron Parecki's [Compass](https://github.com/aaronpk/Compass)
// but other systems are available.
// This also uses DarkSky's API to get the actual weather data.
'weatherToggle' => false,
// The tracker system that the author has used is Aaron Parecki's [Compass](https://github.com/aaronpk/Compass)
// but other systems are available.
// This also uses DarkSky's API to get the actual weather data.
'weatherToggle' => false,
'compass' => 'https://private.tracker.com/api',
'compassKey' => 'PrivateAPIkey',
'forecastKey' => 'DarkSkyApiKey',
@ -66,18 +78,35 @@ Then edit the included `configs.php` file to enable various features. The full f
### Notes
- Mastodon Keys are more command-line driven, but relatively straightforward. See [the Mastodon API documentation](https://github.com/tootsuite/documentation/blob/master/Using-the-API/Testing-with-cURL.md)
- As Mastodon is a federated network, you do need to _explicitly_ specify your Mastodon Instance.
- Mastodon Keys are more command-line driven, but relatively straightforward.
See [the Mastodon API
documentation](https://github.com/tootsuite/documentation/blob/master/Using-the-API/Testing-with-cURL.md)
- As Mastodon is a federated network, you do need to _explicitly_ specify your
Mastodon Instance.
- If using the micro.blog function, you need to specify your site's rss/atom feed.
- To use the weather data, you'll need to add access data for a location-tracking endpoint (like a self-hosted version of [Compass](https://github.com/aaronpk/Compass)) and a DarkSky [API Key](https://darksky.net/dev/docs)
- Twitter Keys can be obtained using the [Create New App](https://apps.twitter.com/app/new) on twitter.
- Since 1.5, you can configure the frontmatter format for your posts. Currently the options are json, used in [Hugo](https://gohugo.io/content-management/front-matter/), or yaml, optionally used in Hugo, but required by other static engines such as [Jekyll](https://jekyllrb.com/docs/frontmatter/) or [Metalsmith](http://www.metalsmith.io). This could be used with other generators, such as [Pelican](docs.getpelican.com/en/stable/content.html), but the script would need to be changed to meet their specific format requirements.
- To use the weather data, you'll need to add access data for a
location-tracking endpoint (like a self-hosted version of
[Compass](https://github.com/aaronpk/Compass)) and a DarkSky [API
Key](https://darksky.net/dev/docs)
- Twitter Keys can be obtained using the [Create New
App](https://apps.twitter.com/app/new) on twitter.
- Since 1.5, you can configure the frontmatter format for your posts.
Currently the options are json, used in
[Hugo](https://gohugo.io/content-management/front-matter/), or yaml,
optionally used in Hugo, but required by other static engines such as
[Jekyll](https://jekyllrb.com/docs/frontmatter/) or
[Metalsmith](http://www.metalsmith.io). This could be used with other
generators, such as [Pelican](docs.getpelican.com/en/stable/content.html),
but the script would need to be changed to meet their specific format
requirements.
You will need to set your site up with the requisite micropub-enabling headers to:
- Use an identity/token service for user authentication (the configs file uses [IndieAuth](https://indieauth.com/setup))
- Identify `nanopub.php` as your site's [micropub endpoint](https://indieweb.org/Micropub#How_to_implement)
- Use an identity/token service for user authentication (the configs file uses
[IndieAuth](https://indieauth.com/setup))
- Identify `nanopub.php` as your site's [micropub
endpoint](https://indieweb.org/Micropub#How_to_implement)
On my site, these headers are provided as follows:
@ -91,7 +120,10 @@ On my site, these headers are provided as follows:
### Data Structure
The location of the data store - where the script places your posts - is set with the `storageFolder` and `trashFolder` config options. This can be set relative to the working directory, or to an absolute path. On my site, I have configured the data store as follows:-
The location of the data store - where the script places your posts - is set
with the `storageFolder` and `trashFolder` config options. This can be set
relative to the working directory, or to an absolute path. On my site, I have
configured the data store as follows:-
```
/srv

97
README.md

@ -3,38 +3,62 @@ MicroPub support for Static Blog Engine
**Note** This release removes support for syndicating to twitter.com.
This php script provides micropub support for Static Site Generators. Incoming posts are rewritten to a suitable front-matter format and saved to the user's content store.
This php script provides micropub support for Static Site Generators. Incoming
posts are rewritten to a suitable front-matter format and saved to the user's
content store.
Currently, the script will handle the following indieweb functions:-
- [notes](https://indieweb.org/note)
- [articles](https://indieweb.org/article)
- [replies](https://indieweb.org/reply), adding the **title** of the article/note you are replying to. Replies can be syndicated to external services.
- [photos](https://indieweb.org/note), note that this functionality _requires_ the use of JSON-posts. **nanopub** is not presently equipped to handle multipart uploads
- [checkins](https://indieweb.org/checkin), this functionality is heavily informed by [OwnYourSwarm](https://ownyourswarm.p3k.io/) and the format that service uses
- [replies](https://indieweb.org/reply), adding the **title** of the
article/note you are replying to. Replies can be syndicated to external
services.
- [photos](https://indieweb.org/note), note that this functionality _requires_
the use of JSON-posts. **nanopub** is not presently equipped to handle
multipart uploads
- [checkins](https://indieweb.org/checkin), this functionality is heavily
informed by [OwnYourSwarm](https://ownyourswarm.p3k.io/) and the format that
service uses
- [bookmarks](https://indieweb.org/bookmark)
- [like-of](https://indieweb.org/like)
- [repost](https://indieweb.org/repost)
**nanopub** offers the following functionality as described in the formal [Micropub Specification](https://www.w3.org/TR/micropub/)
**nanopub** offers the following functionality as described in the formal
[Micropub Specification](https://www.w3.org/TR/micropub/)
Required
--------
- Supports header and form parameter methods of authentication
- Supports creating posts using `x-www-form-urlencoded` syntax
Optional
--------
- Supports updating and deleting posts
- Supports JSON syntax and source content query
- Supports replacement and deletion of limited set of properties
- As it uses a separate Media Endpoint it provides configuration query
[Full implementation report](https://micropub.rocks/implementation-reports/servers/132/dohoQpnIdZYxrwcpMgzj) is available on [micropub.rocks](https://micropub.rocks/)
[Full implementation report](https://dgold.eu/dt1td) is available on
[micropub.rocks](https://micropub.rocks/)
**nanopub** additionally supports syndication of content to external silos. Currently it provides syndication to [Mastodon](https://mastodon.social), although it also provides a framework implementation for any modern API-based endpoint. An example is provided of the script pinging the [micro.blog](https://micro.blog) service to update the user's feed.
**nanopub** additionally supports syndication of content to external silos.
Currently it provides syndication to [Mastodon](https://mastodon.social),
although it also provides a framework implementation for any modern API-based
endpoint. An example is provided of the script pinging the
[micro.blog](https://micro.blog) service to update the user's feed.
The code is self-explanatory and documented, and can be adjusted easily to meet different needs.
The code is self-explanatory and documented, and can be adjusted easily to
meet different needs.
Installation
------------
@ -43,49 +67,68 @@ Please refer to the [Installation Notes](INSTALLATION.md)
Client Notes
------------
**nanopub** expects data inputs in accordance with the current (May 2017) Micropub Spec, and does not gracefully handled deprecated formats. In particular:
**nanopub** expects data inputs in accordance with the current (May 2017)
Micropub Spec, and does not gracefully handled deprecated formats. In
particular:
- `mp-slug`, not `slug` when setting the content of the slug property
- `mp-syndicate-to` not `syndicate-to` when setting syndication targets for POSSE
- `mp-syndicate-to` not `syndicate-to` when setting syndication targets for
POSSE
Any errors resulting from use of the deprecated formats are a matter for the client.
TODO
----
* [ ] Make a `setup.php` script to complete the required configuration settings.
* [ ] Implement rsvp's, itineraries &c
Author
---
* **Daniel Goldsmith** <https://ascraeus.org>
Licences
--------
- **nanopub** is released under the [BSD 3-Clause Clear Licence](https://choosealicense.com/licenses/bsd-3-clause-clear/) (BSD-3-Clause-Clear).
- **nanopub** is released under the [BSD 3-Clause Clear
Licence](https://choosealicense.com/licenses/bsd-3-clause-clear/)
(BSD-3-Clause-Clear).
Acknowledgments
---------------
* The IndieAuth validation sequence was taken from [Amy Guy's Minimal Micropub](https://rhiaro.co.uk/2015/04/minimum-viable-micropub), without which I couldn't have done this.
* All at the #indieweb and #indieweb-dev IRC channels, who provide inspiration and support in equal measure.
* The IndieAuth validation sequence was taken from [Amy Guy's Minimal
Micropub](https://rhiaro.co.uk/2015/04/minimum-viable-micropub), without
which I couldn't have done this.
* All at the #indieweb and #indieweb-dev IRC channels, who provide inspiration
and support in equal measure.
* [@lyda](https://phrye.com)
Changes
-------
Version | Date | Notes
-------:|:----:|:-----
2.0.1| 2019-01-04 | Changed licence to BSD 3-Clause Clear
2.0.0| 2018-08-09 | Removed support for syndication to twitter
1.5.1| 2018-04-12 | Clarified Installation & packaged vendor files
1.5 | 2018-02-01 | Added configurable frontmatter, currently json or yaml
1.4 | 2018-01-26 | Extended for weather reporting, and rich-context likes/reposts
1.2 | 2018-01-02 | Expansion to include `repost` & `like` posts.
1.1 | 2017-11-14 | Rewrite of script to remove redundant and repetitive code.
|||FIX: Added a getallheaders() replacement for web servers without apache functions
1.0 | 2017-10-17 | First official release.
Version | Date | Notes
-------:|:----------:|:------------------------------------------------------
2.0.1 | 2019-01-04 | Changed licence to BSD 3-Clause Clear
2.0.0 | 2018-08-09 | Removed support for syndication to twitter
1.5.1 | 2018-04-12 | Clarified Installation & packaged vendor files
1.5 | 2018-02-01 | Added configurable frontmatter, currently json or yaml
1.4 | 2018-01-26 | Extended for weather reporting, and rich-context likes/reposts
1.2 | 2018-01-02 | Expansion to include `repost` & `like` posts.
1.1 | 2017-11-14 | Rewrite of script to remove redundant and repetitive code.
| | FIX: Added a getallheaders() replacement for web servers
| | without apache functions
1.0 | 2017-10-17 | First official release.
> If someone is able to show me that what I think or do is not right, I will
> happily change, for I seek the truth, by which no one ever was truly harmed.
_Marcus Aurelius, Meditations, VI.21_
>If someone is able to show me that what I think or do is not right, I will happily change, for I seek the truth, by which no one ever was truly harmed.
_– Marcus Aurelius, Meditations, VI.21_
Loading…
Cancel
Save