This documentation is for developers of this prototype OBO Foundry site.
Note this document is in markdown and is best viewed on GitHub.
You will first need jekyll, which can be installed by the ruby gem:
gem install jekyll
After checking out the code from GitHub, you can start a local server:
jekyll serve
(this must always be done from the top level)
Then view http://127.0.0.1:4000
You can make changes locally (you will need to start jekyll again - no hot fixes).
If you commit and push, your change will be visible within a few minutes on: http://obofoundry.github.io
If this site becomes official we may want to institute policies for the site: e.g. major new changes happen on forks/branches, with a voting policy for merging these in.
Because Jekyll can be difficult to install, Docker provides an
alternative for running the serve command:
$ export JEKYLL_VERSION=3.5
$ docker run --rm --volume="$PWD:/srv/jekyll" -p 4000:4000 -it jekyll/jekyll:$JEKYLL_VERSION jekyll serveThe setup is fairly standard for Jekyll. We use Jekyll bootstrap (bootstrap 3). We try and keep things minimal so that the site will work on github. Even if you have no knowledge of Jekyll, it is fairly easy to introspect what is going on if you have done much CMS work or web development.
Basically, every .md or .html file in the directory is visible on
the site, the same path. .md files are automatically translated to
.html.
Jekyll uses a templating system called liquid. The basic idea is simple, templating commands are contained within braces '{ }'.
Pages can have different layouts - see the _layouts/ directory. They can also include templates from the _includes/ directory.
See assets/themes for bootstrap styling - don't touch this unless you know what you're doing.
For the most part no compilation is necessary. Ontology pages are
served directly from the source .md file.
However, for some purposes it may be necessary to recompile the _config.yml file (never edit this directly)
To do this, type:
make
In the top level. Note you will need python3 and the yaml library, as well as jena's rdfcat
pip3 install yaml
jena is at https://archive.apache.org/dist/jena/binaries/apache-jena-3.10.0.tar.gz. Uncompress and then add the bin directory to your PATH
The dependencies should be visible in the Makefile. The basic idea is:
- ontology/*.md --[extract yaml]--> registry/ontologies.yml --> _config.yml
registry/ontologies.yml is also used to create RDF files via a JSON-LD file (JENA required):
- registry/ontologies.nt (in the N-tuples format)
- registry/ontologies.ttl (in the turtle format)
- registry/ontologies.jsonld (in the JSON-LD format)
The front page index.html is the ontology table. It is driven by the _includes/ontology_table.html template.
It iterates through all ontologies (these are stored in the variable
pages.ontologies which is set via _config.yml - see above for how
this is built). For each ontology it writes a table row.
These are displayed directly via jekyll. Each ontology has its own
.md page, which consists of the main page content (free form
markdown) preceded by a structured yaml block. The structured yaml is
the ontology metadata (with a direct mapping to RDF), arbitrarily
nested. See the FAQ for how users should edit this.
The system is fairly simple with no additional compilation outside the
normal jekyll system. Whenever jekyll displays a markdown file, it
examines the yaml block and looks for a tag called layout (users
should not mess with this field unless they know what they are
doing). This determines the template in the _layout directory that
is used to render the markdown.
Currently all pages use the ontology_detail layout, which is found
in
_layouts/ontology_detail.html. What
this currently does (and devs more web-savvy than me are welcome to
contribute different ways of doing this) is display the structured
yaml metadata in the left of the page, and the freeform (compiled)
markdown and html in the center.
The navigation bar / menu on the top of the page is controlled by _includes/navbar.html. It should be easy for site admins to add new items, rearrange etc as they see fit
This site provides a convenient way to organize OBO Foundry docs, if this is deemed appropriate. So far I have copied some docs from the original website (much of which is embarassingly stale, rotten or out of date). Many things at the top level could be moved down into directories to provide better organization.
I have already started a faq/ directory (one md file per FAQ entry).
We could in theory easily manage our principles here. E.g. one .md file per principle. I personally think this much better than the current wiki, but other opinions welcome.
We use bootstrap 3, so far no themes.