PKP Documentation Hub
The repository for generating PKP's documentation hub.
Install Ruby 2.1.0 or higher and install the bundler gem.
gem install bundler
Install Jekyll to build or serve the site.
Serve the site locally.
bundle exec jekyll serve
Orientation to file structure
The index page's data is specified in
_data/index.yml. Each app covered is specified under the
apps property. OJS 3 looks like this:
- path: ojs3 title: Open Journal Systems 3 titleShort: OJS includeInHero: true description: Our flagship software for open access journal publishing, used by more than 10,000 journals worldwide. cards: - path: learning-ojs-3 - path: looking-for-ojs-2 isHighlighted: true - path: developer isDeveloper: true - path: starting-a-journal
pathshould be a unique ID made up of numbers and letters with no spaces.
titleis the main title of the app's section
titleShortis used in the buttons in the hero element at the top
includeInHerocan be set to false if you want to create an app section but don't want it to be listed in the buttons in the hero element at the top
descriptionis a short description that will be placed below the title in the app's section
Each of the
cards provides a
path which points to markdown files in the
_includes/cards directory. Each of these cards represents a resource card that will be added under that app, and you can use markdown to add links. See the next section.
Add a new resource
Create a card under
_includes/cards/<app>/<your-new-resource-name>.md. Give your card a title with three
### [Your resource title](http://link-to-resource.com)
Add a short description below it, and link to the resource.
This resource will help you accomplish X. [View Now](http://link-to-resource.com)
Create multiple sections in your resource card
If you want to add a section to the card, use three dashes before the section:
--- - [Table](/url) - [Of](/url) - [Contents](/url) --- Available in [Deutsch](/url).
Versions of documents
You can link between different versions of the same document. Below is an example using the
importing-exporting document. First, prepare all versions of the document in directories like below. (Notice the latest version has no version number.)
/importing-exporting/en /importing-exporting/2.0/en /importing-exporting/1.0/en
Then add an entry for the version in
importing-exporting: 3.0: /importing-exporting/en 2.0: /importing-exporting/2.0/en 1.0: /importing-exporting/1.0/en
Then add the following to the frontmatter of each
.md file in the document, adjusting the
version entry as appropriate:
--- book: importing-exporting version: 2.0 ---
This should display a link to each version in the header of each
.md file you've modified.
Creating a new version
To create a new version of the document:
- Move the existing
- Move the new version into
The base URL,
/<any-book>/en, should always be the current version so that any internal or external links always point to the most up-to-date resource.
This structure doesn't yet support versioning separate language editions of documents. We can work on that when we need it.
Generate REST API References
The REST API references use SwaggerUI to generate the human-readable documentation from a
.json specification file. To generate this file, you'll need a checkout of the OJS/OMP application repository.
php lib/pkp/tools/buildSwagger.php <path-to-docs/dev/api/<app>/<version>.json
Then create a
.md file in the documentation repository at
/dev/api/<app>/<version>.md. Use the following front-matter:
--- layout: api title: REST API Reference, <version> - Open Journal Systems description: This guide documents the REST API endpoints which will be accessible for Open Journal Systems <version>. It is a technical reference for software developers who wish to build custom interactions with the platform. swagger: /dev/api/ojs/<version>.json app: <app> version: <version> ---
Then create an entry for the version you just added under
Then add a link to this version in the References section of
REST API references should be created for every minor version of an application. Examples: 3.1.x, 3.2.x, 3.3.x.
We also have one version,
dev, which is used for the current in-development version of the API docs. This may not be updated very regularly but can be used to give advanced warning of new endpoints or significant changes.
Every version can include a changelog detailing breaking changes from previous versions of the API. This has to be done in the description of the
.json file for now.