To ease the wiki development process we built a "wiki generator". You can find its source code at https://github.com/igemuoftATG/generator-igemwiki. Check the repo for the most current version of this tool.
kek bro, whats the package name?
npm install -g generator-igemwiki
This generator requires that you have Node.js
installed on your system. If you are on OS X or Linux system, I recommend
installing using one of these methods
to avoid having to
sudo. Furthermore see
to set up npm packages to install into a custom global directory without sudo.
You can check if the install worked by running
in a terminal; it should return the version number. You don't need to worry
about sudo on Windows, as Windows runs as admin by default. However, you may
PATH issues on Windows (see below).
NPM is node package manager and is the "largest ecosystem of open source libraries in the world". All of this project's dependencies are held on npm, and this package is published on npm.
Node comes with npm, though it is usually not the latest version, and more
importantly, it is not located where your global npm modules are installed.
Before continuing, you should make sure your
PATH variable catches the correct
npm binary, or in simpler terms, running
npm -v npm install -g npm npm -v
should return a different value on the second
npm -v. (You may need to open
and close the terminal first). If it is not, compare the path returned by
install -g npm (of the format path -> path) to
which npm. If they are
different, it is because the directory containing Node's npm is earlier in your
PATH than the one containing the binaries of npm's global modules. For
example, I have the following in my
# Node and NPM export NPM_PACKAGES="$HOME/node/npm-packages" export NODE_PATH="$NPM_PACKAGES/lib/node_modules:$NODE_PATH" export PATH="$PATH:$NPM_PACKAGES/bin:$HOME/node/bin" export MANPATH="$NPM_PACKAGES/share/man:$MANPATH"
You can see
PATH is the original PATH, followed by npm-packages, followed by
node. On OS X and Linux, you can add the above to your
etc. to achieve the same effect. To see your environment's
$PATH. Note, I used the two methods mentioned above for not using sudo with
Node and npm, with custom folder names (
npm-packages). On Windows,
you can go to System -> Advanced Settings -> Environment Variables -> Path and
edit it there.
Yeoman is "the Web's scaffoldig tool for modern webapps". To get it, install it globally with npm:
npm install -g yo
Once that is done, you can invoke the Yeoman with
Now we just need to install this generator:
npm install -g generator-igemwiki
Create a new project folder,
cd into it (this generator dumps files into the
current directory), and run
You will be asked for
- the year (will default to current year)
- team name is it appears exactly on the wiki (needed for push to live wiki)
- author (optional)
- GitHub repo in the format username/repo
- Why? As you will see, this generator exposes features which it make it applicable for collobarative content editing when using the repo to modify markdown files.
- Still confused? You can skip this by passing in the option
--skip-repo. You can always push to a repo later.
yo igemwiki --skip-install --skip-repo
--skip-install will prevent
bower install and
npm install from
automatically running. Use this if you know you need sudo to npm install and it
won't work anyways.
--skip-repo will prevent the prompt asking you for your
This generator is built using the following tools. You should have an idea what they are each doing in order to use them effectively.
bower install --save bootstrap
--save is important as it adds bootstrap to the dependencies object in the
bower.json file, and will be used by
wiredep to inject the proper css and
script tags into the outputted html. Browser all the Bower packages
Handlebars is used to write templates. This templates, when combined with helper functions and a set of object values can be very powerful. This is how I am building links for development and live using the same source files. The custom helper functions are all here. This file is much smaller than the gulpfile, and I encourage you to quickly take a look. Using it, we can do things like:
Again, if you write your own helper functions which may be useful to other teams, send a pull request!
Markdown is easy to learn. Markdown provides a way to write clunky HTML without having to write clunky HTML. Huh?
Consider this html for a level 1 heading:
<h1> Wheeeeee </h1>
Okay, that works, but in markdown it is sooo much cleaner:
You can use
<h6>, respectably. Still not convinced?
<img src="http://126.96.36.199/logo_grey.png" /> <ul> <li> <a href="http://igemuoft.github.io">iGEM UofT Computational Biology</a> </li> <li> <b>wheeeee</b> </li> <li> <i>wahooooooo</i> </li> </ul>
![* [ ]( ) * **wheeeeee** * *wahooooo*]( )
Oh and by the way, you just learned markdown. Still curious? See this Markdown Cheatsheet.
Gulp tasks are run with
gulp taskName. A lot of the tasks in the gulpfile are
used internally within other tasks, though these are two you will most
Compiles sass, bundles CoffeeScript and JS, compiles handlebars templates,
compiles markdown, and provides a local version of the wiki at
http://localhost:3000 using Browsersync. (Which
also sets up a UI at
3001 and an external IP to use from your phone, all
build:live and then
push. Same as above but uses
live mode when
compiling templates, and minifies Bower css into
vendor.min.css, personal css
styles.min.css. Likewise for JS, except it uglifies as well, and personal
JS goes into
bundle.min.js. Then using the
request package (in combination with
Chrome's web inspector Network tab), I've emulated to "go to
pageName?action=edit, copy/paste into textbox, click save". You will be asked
for your username and password of course, and will automatically log out when
all uploads are complete.
Run this to download all current live files into
gulp phantom gulp phantom:sync
Spawn up some Phantom process and store screenshots
of your wiki across mobile, phablet, tablet, desktop, and desktophd resolutions
The main template file is at
./src/template.json. This stores the team name,
year, links, markdown files, and navigation bar settings. It's used in almost
every helper function in
./helpers.coffee, and has a mode, either
live appended into it by the gulpfile before being used with handlebars.
If you want to add new pages, change the ordering of the navigation, add new
markdown files, edit this.
Page styles are stored in
./src/sass. There is a file there,
which gets compiled into
./build-dev/css/styles.css. All the other files here
are prefixed with
_ so that they don't compile for themselves (they are
styles.scss). Sass lets you use
variables and functions in CSS, and is super awesome. It's very easy to learn,
if you already know css, you know sass.
You can write JS and CoffeeScript inside
./src/lib. You can use
because Browserify is employed. Everything here will
get bundled into
Pages are written as Handlebars templates in
Markdown files are stored in
./src/markdown/*.md. You can also write inline
markdown using the
Images are stored in
./src/images. They will have
to the filename when uploading.
images.json will store a link to the full
resolution of each image.
For complete detail, read through
Here is a summary of the helper functions which take parameters (other than
mode, which is injected into a new template as either
live for the
build:live tasks, respectably).
images(image, format, mode)
image is the filename exactly as it appears in
./images, including the
format can be:
- "file" -> inline image using wiki code. forces breaking/reopening html
- "media" -> wiki code link to image without showing image, same as above with regards to html
- "directlink" -> The preferred method. Requires
images.jsonto already store the image link.