Introduction
With the Jamboree being held online this year, iGEM wikis have never been more important. Currently, building iGEM wikis requires teams to write code in a text box in their browsers, due to which they miss out on the wide variety of features code editors and integration tools offer these days. Besides, a typical iGEM wiki is anywhere between 15 to 20 pages, so it can quickly become cumbersome to copy and paste for every small change, and sometimes a few changes might just be left out in a hurry. IDEs have become the de facto standard in the web development industry, optimizing various parts of the process and ultimately making it much easier and faster.
Over the years, iGEM teams have come up with several ways to improve this experience. These solutions have focused on multiple aspects of building wikis - from making it easier to write code to uploading it and even implementing continuous integration. iGEM Toronto 2015, Waterloo 2017 and Virginia 2018 did excellent work in this area, with their wiki generators, upload APIs and CI tools. Some of these tools allowed teams to write code locally, in a code editor of their choice, and then upload it to iGEM servers for deployment.
However, while employing their software for our wiki, we realized that much of it is outdated and needs improvements.
However, we felt that there was a need for a holistic solution - something that would cover every aspect of the process. This solution had to be comprehensive enough that teams wouldn't need to find other software to build common components, but it would still allow teams to easily integrate other libraries, should they need to do so. Instead of reinventing the wheel and starting from scratch every year, teams can expand on this base to kick-start their wiki building process.
We identified three key areas to focus on: content, design and deployment.
The way teams design and add content to their wikis usually varies widely, but the deployment process is common, since all iGEM wikis are powered by the MediaWiki engine. Code is written in an IDE, and then manually pasted in the text box on the page where it belongs. This is something that can easily be automated, and something that each team would need, irrespective of which frontend web development library they use.
These days in the web development industry, it is common to set up a version control system like Git, and link that to an automatic deployment service, like Github Actions or Travis. This ensures that every time a change is made in the codebase, it is automatically pushed to servers for deployment. Github Actions and Travis are free for open source repositories, and most website hosting services offer integration with these. However, in order for iGEM teams to use such a service, an integration tool was required, that would allow CI/CD software to upload files to iGEM servers, so we decided to make one!
iGEM WikiSync
Our Python package, iGEM WikiSync allows iGEM teams to set up continuous deployment for their wikis. It lets teams work on their wiki locally, using whichever web development framework they're familiar with. It then uploads the code to iGEM servers.
It does this in the following way:
- WikiSync looks for all assets (images, videos, PDFs, etc.), renames them according to iGEM specification, and uploads them to iGEM servers.
- It then goes through the code (HTML, CSS, JavaScript), scanning it for links.
- It replaces all local links to iGEM.org URLs where the files have been uploaded.
- Finally, all code files are also uploaded to iGEM servers and the team wiki is deployed.
WikiSync keeps track of the files uploaded in each run, so only changes are uploaded the next time it runs. It also checks code for internal broken links and shows warnings.
In order to access files on iGEM servers, WikiSync requires the user ID and password of a team member. These credentials are taken in as environment variables, so that they never have to be stored in plain text, and are discarded when the terminal session ends. When run as part of a CI/CD workflow on Github Actions or Travis, user credentials are stored as "secrets" in the repository, and CI providers ensure that they are never displayed publicly and cannot be accessed by anyone apart from the user themselves.
Documentation and Downloads
WikiSync is available at the following links:
iGEM WikiSync Github Action
By automating uploads, iGEM WikiSync allows teams to save dozens of hours over the course of their iGEM experience. This is made possible by using WikiSync to set up a continuous integration and continuous deployment routine on the wiki's version control repository, such as on Github. For example, for our own wiki, we set up continuous deployment using a Github Action we wrote for iGEM WikiSync that runs every two days, or as requested manually. iGEM WikiSync Github Action is a Github Actions plugin that allows teams to easily set up a Github Actions workflow and integrate iGEM WikiSync into their wiki, so that every time changes are made in the codebase, they're automatically sent to iGEM servers. All that is required is a git push.
Setting it up is a really simple process. Teams can either write their own CI workflows and include the plugin in just a few lines of code, or they can use our readymade recipes for wikis built with webpack, such as those made with our iGEM Wiki Starter Pack. All they have to do is download and include a file in their wiki repository and enable Github Actions for their wiki.
Since this Actions plugin behind-the-scenes runs iGEM WikiSync itself, it also needs access to iGEM.org credentials of a team member. These credentials are stored as "secrets" in the Github repository, so that they are never accessible to anyone apart from the user themselves. In public build logs, they are replaced with asterisks (*).
The Action can be found on the Github Marketplace along with usage instructions and common use cases.
The iGEM WikiSync Github Action is available here:
iGEM Wiki Starter Pack
The iGEM Wiki Starter Package is a template that contains everything needed to build an iGEM wiki and then some. Instead of reinventing the wheel and starting from scratch every year, teams can expand on this base to kick-start their wiki building process.
The out-of-the-box design of the package is clean and modern, scales to mobile devices, comes with a dark mode, and works great with screen readers and the like. All wiki content can be written in plain English (using Markdown) instead of pure HTML, which has poor readability and code to text ratio. Design is also completely separated from content while editing the starter pack; this lets teams customize pages and write content simultaneously, and prevents the workflow from being bottlenecked at either step.
In addition to simplifying content and design, the package includes common web development libraries like Bootstrap (layout), jQuery (JavaScript), MathJax (mathematical notation), and Font Awesome (icons) that add functionality to the wiki. It also features utilities that automate time-consuming tasks like adding citations to your wiki. The title, author, and other publishing information of an article can be retrieved directly from its DOI and included at the end of the page.
The package comes built in with WikiSync This eliminates the need to manually rename and upload each file, replace each URL, and copy paste the source code for each page into their respective editors. WikiSync integrates effortlessly into automation workflows like GitHub Actions and Travis CI, so content added to the team’s wiki repository on GitHub is automatically uploaded to the iGEM servers every time.
Features
- Built-in theme that
- Looks great on all devices
- Comes with a dark mode
- Markdown support
- Automatic uploads with WikiSync
- Extract citation information from DOI
- Automatic table of contents on each page
- Customization with Webpack
- Included common web development libraries
- Bootstrap
- jQuery
- MathJax
- Font Awesome
- Extensive templating using Pug
- Reset styles on iGEM.org
Documentation and Downloads
The iGEM Wiki Starter Pack is available at the following links:
Acknowledgements
The following teams developed their wikis this year using our software and provided feedback towards its improvement. We're grateful for their support in testing and improving the documentation of our software.
- iGEM Stockholm
- iGEM MIT MAHE
- iGEM UNSW Australia
- iGEM Virginia
- iGEM UGent Belgium
- iGEM NYU Abu Dhabi
- iGEM IIT Roorkee
- iGEM GZ HFI