BBP GitHub Wiki Tips
Markdown Editing
Editing markdown files offline with Atom is a good option. It is possible to right-clicking the markdown file name on the file viewer panel and then select the "Markdown Preview" option. Atom will then render the markdown file inside the editor, including images and links.
For adding images to the markdown document, one option is to check out the repo to a local machine, add a new directory (e.g. 'images') and copy all images (e.g. png files) there. Then, links can easily be created with something like:
This approach works for both the Wiki and also with markdown files in the main repo.
For PDF files, an option is to create a 'pdfs' directory and do the same. For example:
[Graves & Pitarka (GP)](pdfs/BBP-GP-2019-04-02.pdf)
One caveat is that, in Safari, clicking the link will download the file instead of opening the PDF inside the browser.
For linking other markdown files there's a small syntax difference between the Wiki and the main repo. Here's the syntax for the two:
Wiki
[File Formats](./File-Format-Guide)
Main Repo
[File Formats](./File-Format-Guide.md)
Since, for the Broadband Platform, we have a copy of the documentation within the main repository, it would be ideal to use the same syntax so that we would have a single copy of these files on both the Wiki and on the BBP documentation in the main repo. However, note that the syntax for the main repo includes a ".md" extension on the filename. On the main repo, the '.md' extension is required so that clicking on the link using the GitHub web interface will work properly. On the other hand, adding the ".md" extension to the Wiki copy of the file it will work but will display the unrendered file -- which is not what we would like. At this point, we need to create two separate versions of these files to use on the main repo and the wiki.
Finally, for both images and links to other markdown files, there is no need for using full URLs, the relative paths work.
