DevNotes_Processeses_WebPageInstructions

How to update the web pages

The SasView web pages while not strictly managed by a Content Management System such as WordPress or Drupal, operate on the same principal of separating the content editing from the site programming. Content is stored in a series of markdown files (.md), which are then used to automatically generate the html used on the site.

Overview

The sasview.org web pages are hosted on GitHub at ​https://github.com/SasView/sasview.github.io. To edit the pages, you must be a member of the web team. Once you are given editing privileges, check out the repository like you would any other git repository. As changes are made to GitHub, the website changes will automatically go live. NOTE: This page ONLY discusses editing the content. Making more substantial changes should only be made by someone who understands how jekyll works.

Content editing basics

As previously mentioned, all content is contained in a markdown file (*.md). However not all of these even should be touched as they are being auto generated. Files not to touch include publications.md and search.md. In addition README.md and CHANGELOG.md are special files and not part of the content. A convenient Markdown cheatsheet can be helpful when writing content.

All content Markdown files have the following format:

---
layout: XXX
title: A Descriptive Title
tags: [tag1, tag2, ...tagN]
highlight: YYYY-MM-DD
---

Start of your content Here

• layout is required. Currently there are only two types of layout defined: page and post.
• title is required and will be visible on the site as the title of the page to be displayed. An example of a title might be: Version 4.1.1 OR FAQ
• tags is optional but ONLY used for post type layouts. there can as many tags as appropriate separated by commas but should be limited in number to stay useful. It would also best to use existing tags used on like posts so it can be easily found. An example of tags might be: [release, download]
• highlight is an optional flag for posts used to pin the post to the top of the page until the date given
• including images: If you want to include images see the Markdown cheatsheet, but place the actual image file in the img subdirectory (i.e. sasview.github.io/img)
• including Downloadable file: If you want to include downloadable contend such as a PDF file again see the Markdown cheatsheet to create the link but now place the file to download (being linked to) in the downloads subdirectory (i.e. sasview.github.io/downloads)
• To change the content of any news item (posts) or web page, go to the relevant *.md file and edit as appropriate.

Adding a news item to the front page

Items on the front page are treated as news posts and thus of layout type post. These all reside in the _posts folder (i.e. sasview.github.io/_posts). The filename starts with the date it should be posted (and defines where it shows up on the front page). File names are thus yyyy-mm-dd-A_Descriptive-name.md. A quick way of making sure you have the right formating would be to git copy a previous post and edit the name (giving it the right date) and changing the title, tags and content to suit. once committed and pushed back to origin (github) the magic in the other files will automatically pick up the new post and display it (but only if the current date is later than the date of the file name).

Adding a new page to the menu

Adding new webpages to the site consists of two parts:

• Add a new *.md file to the root directory (i.e. sasview.github.io). Again, one can either create a new one from scratch or git copy an existing file and edit it. The layout should be page.
• Edit the _config.yml file to add this new page to the menu bar. To do this, go down to the the #List of links in the navigation bar section and add it in the appropriate place in the existing menu section using display name: "filename" where filename does not include the .md

Editing the list of publications

If you want to edit the publications page, please read the publications web page instructions.

Git Tutorial

Git tools that are available include:

• Eclipse (or some other IDE)

• GUI git (like tortoiseGit for example) - this will require having valid credentials. In principle this is not required for check out but will make checking in much simpler.

• Command line git*. For this type:

  $ git clone https://github.com/SasView/sasview.github.io.git
  

If you already have the repo locally you just need to update the repo

$ git fetch origin

Once the changes are made they should be staged and committed. If using the command line:

$ git commit -a -m 'commit comment'

Finally, the commit will need to be pushed up to GitHub from the local repo. Again if using the command line

$ git push origin master

*The command line examples shown here make a few assumptions about your setup. If they do not work you should look into your git documentation.