Wordpress to jekyll migration
In October 2018, ns-3 migrated from a Wordpress-based site to a Jekyll site. The Jekyll source for the new site is maintained in a git repository (for now, located at https://gitlab.com/tomhenderson/nsnam-web).
The old ns-3 site can be found at http://nsnam-www2.coe-hosted.gatech.edu (note 'http' not 'https').
The new website is written in a new framework (Jekyll) based on Markdown syntax. We want to convert most of the old wordpress site to Jekyll pages. The content migration therefore consists of finding a page not yet ported on the old site, and writing a Markdown-based equivalent, and sending it to us.
The following guide shows how to perform local editing and testing of a content migration.
Note: This google doc is tracking who is working on which portions, so please consult it to avoid duplicate work: https://docs.google.com/document/d/1XzLUKzKXilCYWE8EO67ecopk81YZtOJtBMyWYLs16-Y/edit. See also below about which pages to prioritize.
An example of the type of contribution we are seeking can be found in Michele Polese's merge request: https://gitlab.com/tomhenderson/nsnam-web/merge_requests/3
The first step is to install Jekyll which is based on ruby. I followed this guide for Linux Mint 18:
but I had to add some extra gems not mentioned there.
In short, I did:
$ sudo apt-get install make build-essential ruby ruby-dev $ cd ~ $ mkdir gems $ export PATH=$PATH:$HOME/gems/bin $ export GEM_HOME=$HOME/gems $ gem install bundler $ gem install jekyll jekyll-feed jekyll-seo-tag
Fork or clone the repository
Find a directory to download the files. There are two options, either to clone the repository from gitlab (git clone https://gitlab.com/tomhenderson/nsnam-web/), or fork it using the GitLab web interface, and the clone the fork to your system. The fork option later allows one to generate a 'Merge Request' towards the repository. If you are unsure about this, one can simply clone the repository and work on it and send a patch.
$ mkdir workspace $ git clone https://gitlab.com/tomhenderson/nsnam-web/ $ cd nsnam-web
Try to run a local instance
You should now be able to call 'jekyll build' and have the site build like this:
$ jekyll build Configuration file: /path/to/nsnam-web/_config.yml Source: /path/to/nsnam-web Destination: /path/to/nsnam-web/_site Incremental build: disabled. Enable with --incremental Generating... Jekyll Feed: Generating feed for posts done in 1.17 seconds. Auto-regeneration: disabled. Use --watch to enable.
All built files are deposited into the directory '_site'. Cd into the directory, and try to run 'jekyll serve':
$ cd _site $ jekyll serve
If it succeeds, something like the following should be displayed:
Configuration file: none Source: /path/to/nsnam-web/_site Destination: /path/to/nsnam-web/_site/_site Incremental build: disabled. Enable with --incremental Generating... done in 0.069 seconds. Auto-regeneration: enabled for '/path/to/nsnam-web/_site' Server address: http://127.0.0.1:4000 Server running... press ctrl-c to stop.
and you should be able to open your browser to the following address: 'localhost:4000' and see the ns-3 website. This allows you to test whatever changes you make to the source files (just make sure to run 'jekyll build' again after every change).
To automatically rebuild and serve your local website upon changing a source file, pass the '--watch' flag as follows:
$ jekyll serve --watch
If you get an error because your local port 4000 is already in use, you can redirect to a different port like this:
$ jekyll serve --watch --port 4444
Pages are located in the top level directory, with a '.md' suffix, and posts (news items) are in the _posts directory.
To make edits to an existing page, just provide the edits and rebuild with 'jekyll build'. For instance, I fixed a spelling error on the '_posts/2018-09-04-ns-3-29-released.markdown' page recently. The old text was:
The ns-3.29 release is dedicted to the memory
which contained a spelling error. The new page was fixed, and once I fixed it, I could run a 'git diff' to note the changes:
diff --git a/_posts/2018-09-04-ns-3-29-released.markdown b/_posts/2018-09-04-ns-3-29-released.markdown index 394c4b9..f063e53 100644 --- a/_posts/2018-09-04-ns-3-29-released.markdown +++ b/_posts/2018-09-04-ns-3-29-released.markdown @@ -6,7 +6,7 @@ categories: news excerpt_separator: <!--more--> --- -The ns-3.29 release is dedicted to the memory of project co-founder [George Riley](https://www.ece.gatech.edu/news/607255/loving-memory-george-riley). Contributions from [thirty-two authors](https://www.nsnam.org/ns-3-29/authors/) led to the ns-3.29 release, featuring the following additions: +The ns-3.29 release is dedicated to the memory of project co-founder [George Riley](https://www.ece.gatech.edu/news/607255/loving-memory-george-riley). Contributions from [thirty-two authors](https://www.nsnam.org/ns-3-29/authors/) led to the ns-3.29 release, featuring the following additions: * An HTTP model based on a 3GPP reference model for HTTP/1.1 * A priority queue disc (PrioQueueDisc) for the traffic control module * A model for the TCP Proportional Rate Reduction (PRR) recovery algorithm
If I piped the output into a file, I could send the patch file to an ns-3 maintainer:
$ git diff > patch-to-send.patch
Creating a new page
New posts (for the news feed) follow the convention of a date-formatted filename; e.g. 2010-03-22-welcome-to-jekyll.markdown and then are prefixed with metadata:
--- layout: post title: "ns-3.29 released" date: 2018-09-04 13:55:18 -0700 categories: news excerpt_separator: <!--more--> ---
New posts should be added into the _posts directory.
For new pages, try to come up with a page name related to the title, using hyphen separators, and an .md suffix.
This allows you to set which pages you want to appear in the submenu navigation area in the sidebar of basic pages and configure order and hierarchy of the links. Edit the nav.yml file in the _data directory. Nest sub-pages underneath their parent page with the sub parameter. Make sure to include the link title, and the href must match the permalink of the page:
- title: Support href: /support/ sub: - title: FAQ href: /support/faq/ - title: Report a Bug href: /support/report-a-bug/
Pages to prioritize
Please see this page to coordinate work and avoid duplication: https://docs.google.com/document/d/1XzLUKzKXilCYWE8EO67ecopk81YZtOJtBMyWYLs16-Y/edit
Please prioritize these pages:
- All WNS3 pages (in the Overview) section
- All Release pages
Pages already done
Topics under the 'Developers' heading (such as Contributing code)
Pages that probably will not be migrated
Please do not bother with the following pages; they will not likely be ported to the static site: