👉 Download the latest Framework for Managing University Open Source Software PDF
Welcome to the source repostory for the "Framework for Managing University Open Source Software" document! This document is a results of the NORF funded MOSS-I project. We aim to continuously update and improve the document, and welcome contributions from the community. Furthermore, we encourage individuals and organisations to fork this repository, to create and formulate their distinct versions.
This repository contains the main source for the Framework for Managing University Open Source Software document in the form of a markdown document in the main folder called FrameworkManagingUniversityOSS.md (to learn more about markdown, see this "cheatsheet"). Using the processes detailed below this markdown file is converted to a PDF file called FrameworkManagingUniversityOSS.pdf contained in the output folder.
The PDF document produced here is generated from the markdown using a custom version of the Eisvogel template. The main changes implemented here are the rendering of authors, the addition of DOI links, the addition of Orcid and ROR links, and the modification of the header and footer. The template used here can be found in the /assets/templates folder and is called eisvogel.tex.
The reference style currently used is the IEEE style as per the ieee.csl file provided in the main repository. Other styles may be found in the Citation Style Language - Style Repository. If an alternative style is used its .csl file should be added to this repository, and the "pandoc command" in the YAML defining the GitHub action should be adjusted.
The GitHub is defined by a YAML file (see below) found in the .github/workflows folder. The action (to convert the markdown document to a pdf file) is triggered uppon a push to the repository.
Assuming pandoc is installed you can run the following locally (from a terminal navigated to the main project folder) to build the PDF:
pandoc FrameworkManagingUniversityOSS.md --output=output/FrameworkManagingUniversityOSS.pdf --template assets/templates/eisvogel.tex --listings --number-sections --bibliography=bibliography.bib --citeproc --csl ieee.csl
The below reproduces a so called YAML file which configures a GitHub action to trigger the updating of the repository hosted PDF when a push occurs. Here the YAML file is called markdown2pdf.yml and is found in the .github/workflows folder. Glossing over the YAML file one may see it sets up pandoc, issues a command using pandoc to export the FrameworkManagingUniversityOSS.md file to a file called FrameworkManagingUniversityOSS.pdf using the template called eisvogel.tex. Once completed the next step configures git and adds and commits the updated PDF file. Finally the PDF is pushes to the repository.
name: markdown2pdf
on: [push, pull_request]
jobs:
convert_via_pandoc:
runs-on: ubuntu-22.04
steps:
- uses: actions/checkout@v4
- uses: docker://pandoc/extra:3.5
with:
args: FrameworkManagingUniversityOSS.md --output=output/FrameworkManagingUniversityOSS.pdf --template assets/templates/eisvogel.tex --listings --number-sections --bibliography=bibliography.bib --citeproc --csl ieee.csl
- uses: actions/upload-artifact@v4
with:
name: output
path: output
- name: Commit files # transfer the new pdf files back into the repository
run: |
git config --local user.name ${{ github.actor }}
git config --local user.email ${{ github.actor }}@users.noreply.github.com
git add .
git commit -m "Updating pdfs"
- name: Push changes # push the output folder to your repo
uses: ad-m/github-push-action@master
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
force: true
If you'd like to help improve this project, we welcome all contributions! Your contribution can be anything, e.g. language changes, code improvements, or documentation. For more information we refer to the contributing guidelines. All contributors and team members are expected to act in accordance to the project's code of confuct.
The code/software shared here is licensed under the MIT open source license. All other assets shared here, such as documents and images, are licensed under the Creative Commons CC-BY-4.0 license.