Now that you understand the basics of GitHub, this chapter explains how to add new documents and edit documents in the repository.
If you want to edit existing documentation or add a section or chapter to existing documentation, you can edit the document directly from the docs repository itself.
If your edits requires you to replace or add images, see section on Adding/Replacing images.
When you create a new document, you need to decided whether to make it a single page document or multi-page document, as they are significantly different.
Single page documents are rendered fully from one markdown file. The table of contents on the side of the page is created using the header tags in markdown. For example:
## The "Documentation Hub" ### Single Page Docs
To create a new single page document in GitHub:
--- generateHeadingToc: true ---
From here, write the document out as you would using markdown. Any level two header (e.g.:
## text) displays on the table of contents on the left as a chapter. Any level three header (e.g.:
### text) displays as a sub-chapter. Levels four and up does not display on the sidebar table of contents.
Headings should never skip a level. Do not jump from
## Heading(2) to
#### Sub-heading(4). It is important that a sub-heading of
## Heading(2) is
### Heading(3) for accessibility.
Multi-page documents, like Learning OJS 3, are more robust directories with folders for individual languages/translations, and a single markdown file for every chapter of the document. They also contain a file called
SUMMARY.md that creates the table of contents for the document and a file called
README.md that serves as a first/landing page for your document. To create a multi-page document start with the following:
index.mdfile should contain a description of the document. Look to other documents as examples. Also, if the document is available in more than one language, they should all be linked from this page.
--- isBookIndex: true ---
Unlike with a single-page document, you no longer need to add to index.md. The rest of your document steps should be as follows:
SUMMARY.mdis the file that determines the display of the table of contents for your document. The markdown list hierarchy determines the nesting of contents titles in your sidebar. Each chapter title is written as a link to either a single markdown file per chapter or as a link to a specific heading within that markdown file.
README.mdwhich should be a language specific version of the text you had in
SUMMARY.mdto allow for links to specific sections.
A note on formatting: whereas your headers in single documents create the sidebar TOC, in multi-page docs, this is handled by the
SUMMARY.mdfile. As a result, you’ll want each chapter title as an H1, with all subtitles ranging from H2 to H5. Since you can add to the TOC manually, you can include chapters there as you see fit.
Adding images to your documentation helps users more easily locate the features you are writing about. Images should go in a folder named assets. The type of document you’re working on changes where you will find the assets folder.
To add new images to a document, you will need to take and save these screenshots locally. Make sure to follow the naming convention for images.
New assets can be added before working on a document or after it has been completed.
To add assets to a document and assets folder:
“!(./assets/ image file name)”e.g.,
While you’re editing a document you may find that you need to replace an image with an updated screenshot. This might be the case with version updates.
First, take the new screenshot and update the link to the screenshot in the document.
If you’ve replaced images and there is no longer a use for the previous saved asset, the old assets can now be deleted. Before deleting the old assets, look through the chapter to make sure that these are not being used in other sections of the document. If so, update the other links with the new file name. You can then delete the old assets from your branch and create a pull request.
To create an asset folder within the document branch, you will need to create a new file by clicking ‘Create new file’ in your repository.
This will prompt you to another page where you can edit a new file. On the top you will see:
Here you will enter the main document folder and the subsequent folders. This will vary depending on whether you are creating an asset folder for a single on multi-page document.
Begin by entering the main folder name followed by ‘/’. You will do this until you reach the subfolder you want to create your asset folder within.In a single-page document the asset folder might be created as the second level folder (i.e.,
pkp-docs/contributing/assets/). In a multi-page document the asset folder might be created within the language folder of the document you are working on. (i.e.,
For this example, I have created an assets folder within the en folder of learning-ojs.
As Github will not allow you to create a blank folder, you will need to create a document in the asset folder. Remember that document pages need to end with ‘.md’
This can be labelled as anything, as it will be deleted after you’ve uploaded your assets. Enter some text into the textbox and commit the change to the file.
You should find your newly created assets folder within the main document folder. Click upload files on the top right corner.
Add your assets using drag and drop or by clicking ‘choose your files’
Once you’ve uploaded assets into your assets folder you can go ahead and delete the holder document file you created, by clicking the file name followed by trash can icon on the top right corner.
Once you’ve completed the made edits to the file, you will scroll down and fill the information in the text boxes and click ‘Propose file change’.
This will bring you to another page that compares the changes you’ve made.
The fourth box (highlighted in red) is the branch that’s automatically created by Github.
Click ‘Create pull request.’
This page is where you would enter a more detailed description of what you changed. You might want to do this if you need to justify your changes or need to let everyone else know that a change is significant.
In this final page, you also have the option to create your pull request or create a draft pull request. A pull request indicates that you have completed your changes and lets the PKP team members know to review your changes. Meanwhile, a draft pull request allows you to continue to make changes.
If you are a member of the PKP team, you’ll see the ability to commit directly to the main branch. It’s important to note that these changes are immediate, but they are also unreviewed. Please do not commit directly to main. We recommend that you always commit code via pull request.
Once you’ve created a draft pull request, you can continue making changes to the document you’re working on at any time. It will be important to note which branch is created for that particular document, especially if you have multiple branches in your repository.
Again, the branch that has been created will be listed on the forth box in the Comparing changes page when generating a pull request.
You can also find out the branch by looking at the PKP Repository, pull request tab. Any active pull requests made can be found in the pkp repository page under pull request. Here you will find both draft pull requests and pull requests made.
From your own repository, you will want to select the correct branch and continue making the changes to the document. After making these changes and providing the details of the changes in the textbox. You will want to select the first option to ‘Commit directly to the branch’.
You will repeat this step until you’ve complete making your changes.
Once you’ve completed making the changes to your document. You can now go back to the draft pull request you created and click ‘Ready for Review.’