Skip to content
A repository for generating PKP's documentation hub.
CSS HTML JavaScript Ruby Shell
Branch: master
Clone or download
amandastevens Updated summary
Added User Authentication and Single Sign-on chapter
Latest commit b1c5b4f Oct 16, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
_data card and index file Sep 20, 2019
_includes card and index file Sep 20, 2019
_layouts remove hard coded ids, add a label Aug 20, 2019
_sass Break long links’ texts Sep 17, 2019
admin-guide Updated summary Oct 16, 2019
contributing Minor formatting proposals Sep 25, 2019
crossref-ojs-manual update to crossref doc language Sep 16, 2019
crossref-ojs2-manual corrections to crossref manual Jul 31, 2019
css #38 reverting character encoding non-fix Aug 24, 2018
designing-your-journal Fixed proper name of software on paragraph 39 Sep 27, 2019
dev Add pkp git as remote repository Aug 22, 2019
documentation-guidelines Fixed internal link in paragraph #37 Sep 10, 2019
doi-plugin https links, headings in troubleshooting section, update old gitbook … Sep 16, 2019
gdpr gdpr card changed from pdf link Nov 19, 2018
getting-found-staying-found Merge branch 'master' into crossref-docs-update Jul 31, 2019
img add pkp docs image and tweak css to account for size differences Feb 14, 2019
importing-exporting crossref docs update Jul 31, 2019
learning-ojs-2 crossref docs update Jul 31, 2019
learning-ojs Merge pull request #257 from kant/patch-15 Sep 27, 2019
learning-omp learning-omp docs added Jun 18, 2018
ocs-quick-guide port OCS quick guide from PDF to MD Jun 28, 2019
ojs-2-technical-reference Update preface.md Dec 19, 2018
ojs Add a basic search capability Apr 12, 2018
ojsdesearch-and-the-solr-lucene-plugin ojsdesearch doc migrated Jun 21, 2018
orcid Minor fix (proposal) on line 57 Sep 11, 2019
pkp-theming-guide remove hard coded ids, add a label Aug 20, 2019
starting-a-journal Updated links Jul 12, 2018
student-toolkit Updated Copyright Oct 4, 2019
translating-guide deprecate code-organization from translation docs Jul 30, 2019
using-paypal-for-ojs-and-ocs update language names to be displayed in their own language Apr 8, 2019
.gitignore Update .gitignore Aug 2, 2019
Gemfile Google: generating sitemap.xml to index content. Dec 7, 2018
Gemfile.lock updates to gemfile and .gitignore for analytics Dec 12, 2018
_config.yml Google: generating sitemap.xml to index content. Dec 7, 2018
favicon.ico add favicon Jun 7, 2019
index.md
readme.md README update Nov 6, 2018

readme.md

PKP Documentation Hub

The repository for generating PKP's documentation hub.

Usage

Install Ruby 2.1.0 or higher and install the bundler gem.

gem install bundler

Install Jekyll to build or serve the site.

bundle install

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
  • path should be a unique ID made up of numbers and letters with no spaces.
  • title is the main title of the app's section
  • titleShort is used in the buttons in the hero element at the top
  • includeInHero can 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
  • description is a short description that will be placed below the title in the app's section
  • cards see below

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 /data/versions.yaml:

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:

  1. Move the existing /importing-exporting/en to /importing-exporting/<version>/en.
  2. Move the new version into /importing-exporting/en.
  3. Update /_data/versions.yaml appropriately.

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.

Multiple languages

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 /_data/versions.yml.

Then add a link to this version in the References section of /dev/api/index.md.

Version Pattern

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.

Changelog

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.

You can’t perform that action at this time.