The Learn Text Vis Website
To work on the site locally, you will need a few things.
First, we need to clone the site locally and navigate to its directory:
git clone git@github.com:learntextvis/learntextvis.github.io.git
cd learntextvis.github.ioThis site is powered by Jekyll, a popular ruby static site generator.
The ruby gem dependencies are managed by Bundler.
First, ensure bundler is installed:
gem install bundlerNow we can use the bundle command to install all the packages required for this site.
bundle installThis command will read the local Gemfile and download the required ruby gems.
Assuming everything installs without issue, you should be able to start a local server to serve this site using:
make watchThe site should be accessible from http://localhost:4000/.
Behind the scenes, this is really just running jekyll. It is equivalent to this command:
bundle exec jekyll serveThe Make command just makes it easier to remember.
Almost all the content for the site is in the _posts directory.
Each "chapter" is its own markdown file. The naming convention follows the following convention:
YEAR-MONTH-DAY-cXX-NAME.mdThe date in the name is a requirement of Jekyll - as it is traditionally used for blog posts. Here, we have used the same date for each chapter - so that the order is based on the cXX component of the name.
The NAME section is optional and provides some details on the contents of the chapter.
Chapters are written in Markdown. Each chapter file starts with a "preamble" that starts with and ends with three dashes - ---. This is a Jekyll feature that allows us to add meta-data to our chapters. Currently, we are using title and description to provide content on the home page.
The markdown provides the ability to do code snippets and syntax highlighting. We just use the three backticks and append the language the snippet should be highlighted as:
```python
```
We can also use gists if the external hosting is desirable for some snippets.
Right now, we just have one additional page besides the chapters. index.md controls the content for the home index.html page.
Other pages outside of chapter contents, like an 'about' page are easily created - when we need them.
The preamble also indicates the layout that the file will use. A layout is just a templating system. We currently have 2 layouts - one for posts and one for the main page. They are stored under _layouts.
A layout or a page can also include a fragment of html stored in _includes. Includes are used to ensure the header and footer are consistent between layouts. As more reusable snippets are identified, we can move them into _includes.
The site uses SASS for its styling. Each page, include, or layout can have its own .scss file in the _sass directory.
These files should be @included in css/main.scss. The Jekyll build system and gh-pages both support SASS for styling.
This site is considered a github organization page.
As such, simply pushing local commits to the master branch of this repo on Github will republish the site with any changes. It might take a minute or two to see updates live.
The url for the site is currently: http://learntextvis.github.io/.
We will be able to have our own custom domain name as well - like learntextvis.com - in the future.