Team:Toronto/Generator
To ease the wiki development process we built a "wiki generator". You can find its source code at https://github.com/igemuoftATG/generator-igemwiki.
generator-igemwiki
Yeoman generator for iGEM wikis. Sets up a development environment with the ability to push entire codebase (including images) to live wiki pages.
Install
kek bro, whats the package name?
npm install -g generator-igemwiki
Node.js
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
here
to set up npm packages to install into a custom global directory without sudo.
You can check if the install worked by running
node -v
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
face some PATH issues on Windows (see below).
NPM
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 npm
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 .bashrc:
# 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 .bashrc or .profile,
etc. to achieve the same effect. To see your environment's PATH, run echo
$PATH. Note, I used the two methods mentioned above for not using sudo with
Node and npm, with custom folder names (node, and npm-packages). On Windows,
you can go to System -> Advanced Settings -> Environment Variables -> Path and
edit it there.
Yeoman
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 yo
Generator
Now we just need to install this generator:
npm install -g generator-igemwiki
Usage
Create a new project folder, cd into it (this generator dumps files into the
current directory), and run
yo igemwiki
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.
Options
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
repository.
Tools
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
Bower is "a package manager for the web". Use it to install frontend dependencies, such as bootstrap or fontawesome (todo: push font files to wiki*). Install packages like so:
bower install --save bootstrap
The --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
here.
Gulp
Gulp is a JavaScript task runner. It is the tool running everything behind the development environment, build scripts, and push to live wiki. You don't need to understand it's internals, and I will go over the tasks it provides. Everything is in the gulpfile. Feel free to add your own tasks and submit a pull request!
Handlebars
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:
{{capitals teamName}}
To get
TORONTO
Again, if you write your own helper functions which may be useful to other teams, send a pull request!
Markdown
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:
# Wheeeeee
You can use # to ###### for <h1> to <h6>, respectably. Still not convinced?
<img src="http://45.55.193.224/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>
vs.
* [iGEM UofT Computational Biology](http://igemuft.github.io)
* **wheeeeee**
* *wahooooo*
Oh and by the way, you just learned markdown. Still curious? See this Markdown Cheatsheet.
Tasks
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
commonly run:
Default
gulp
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
connected!)
Push
gulp push
Runs 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
into 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.
Pull
gulp pull
Run this to download all current live files into ./pulled.
Phantom
gulp phantom
gulp phantom:sync
Spawn up some Phantom process and store screenshots
of your wiki across mobile, phablet, tablet, desktop, and desktophd resolutions
in ./phantom/mobile, ./phantom/phablet, ...
Important Files
Template
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 dev or
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.
Styles
Page styles are stored in ./src/sass. There is a file there, styles.scss
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
imported within 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.
Scripts
You can write JS and CoffeeScript inside ./src/lib. You can use require syntax
because Browserify is employed. Everything here will
get bundled into ./build-dev/js/bundle.js
Pages
Pages are written as Handlebars templates in ./src/*.hbs.
Markdown
Markdown files are stored in ./src/markdown/*.md. You can also write inline
markdown using the markdownHere helper.
Images
Images are stored in ./src/images. They will have teamName_YEAR_ appended
to the filename when uploading. images.json will store a link to the full
resolution of each image.
Helper Functions
For complete detail, read through
helpers.coffee.
Here is a summary of the helper functions which take parameters (other than
mode, which is injected into a new template as either dev or live for the
build:dev and build:live tasks, respectably).
images(image, format, mode)
image is the filename exactly as it appears in ./images, including the
extension. 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.