This project is unmaintained. A feature-complete igemwiki-api is available, which is stable and can be used for upload/download of your wiki files.
Yeoman generator for iGEM wikis. Sets up a development environment with the ability to push entire codebase (including images) to live wiki pages.
We are not responsible for your wiki not being completed on time. Do not leave it to the last day. We are not responsible for you losing your current wiki. Run a
gulp pulland back that up before you ever do your firstgulp push. If you have problems open one, or email the author/collaborators identified inpackage.json.I may not be able to keep this project up to date as the years go by and as I am become less active within my school's iGEM team. If things like webpack, gulp, handlebars, (or other templating libraries: EJS, Pug, etc), (or other view libraries with server side rendering: React, Vue2, Angular2), headlessly uploading content, JavaScript, CSS and its ecosystem of preprocesors (SCSS), or even CSSNEXT, markdown based content, continous integration on a github pages site, etc, do not scare you (in fact, they should excite!), then please get in touch with the author.
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
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 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 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
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
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.
Example
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. Not using a repository is not recommended. You should setup a repo, run a gulp pull, then push the pulled folder to GitHub, so that you have a backup.
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 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. Browse all the Bower packages
here.
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 is used to write templates. These 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 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:1234/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.
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:
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!)
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 the "go to
pageName?action=edit, copy/paste into textbox, click save" workflow some of
you might be familiar with. You will be asked for your username and password of
course, and will automatically log out when all uploads are complete.
gulp pull
Run this to download all current live files into ./pulled.
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, ...
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.
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.
You can write JS and CoffeeScript inside ./src/lib. You can use require syntax
because Browserify is used. Everything here will
get bundled into ./build-dev/js/bundle.js
Pages are written as Handlebars templates in ./src/*.hbs.
Markdown files are stored in ./src/markdown/*.md. You can also write inline
markdown using the markdownHere helper.
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.
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).
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 htmlmedia-> wiki code link to image without showing image, same as above with regards to htmldirectlink-> The preferred method. Requiresimages.jsonto already store the image link.