Wordpress to jekyll migration

From Nsnam
Jump to navigation Jump to search

Main Page - Roadmap - Summer Projects - Project Ideas - Developer FAQ - Tools - Related Projects

HOWTOs - Installation - Troubleshooting - User FAQ - Samples - Models - Education - Contributed Code - Papers

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

Install Jekyll

The first step is to install Jekyll which is based on ruby. I followed this guide for Linux Mint 18:

https://computingforgeeks.com/how-to-install-jekyll-on-ubuntu-18-04/

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

Editing pages

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.

Customize sidebar submenu navigation links

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:

  • Overview/Publications
  • Overview/Statistics
Retrieved from "https://www.nsnam.org/mediawiki/index.php?title=Wordpress_to_jekyll_migration&oldid=11390"