Home » SSTDocumentation » SST Simulator Website

SST Simulator Website

SST Simulator Website

Introduction

sst-simulator.org is the main website for the SST Simulator project. It is hosted on GitHub Pages which is a hosting server for static web sites.

Where is it located

sst-simulator.org source files exist on GitHub in the sstsimulator/sstsimulator.github.io repository. Anyone wanting to modify the files must have a GitHub account and the appropriate permisions. If you encounter difficulties, go to the SST Support page.

Markdown

The primary engine behind GitHub Pages is Jekyll. Jekyll allows the user to develop web content in either raw HTML or Markdown (a text to html authoring language) and automatically converts into a usable static html website.

Examples of Markdown syntax

Examples for Markdown syntax and supported features is located here.

The source file for this page may need to be examined to better understand the proper syntax.

Liquid and Kramdown

In addition to Markdown, Jekyll uses:

Liquid (a template engine). This provides programatic support on generating content (such as include files, loops, string manipulation, comparisons, etc.)
Kramdown a Markdown to html conversion processor. Kramdown has a number of extensions (Table of contents, manipulation of html elements, etc.) to Markdown.

GitHub Pages Information

GitHub Pages References:

GitHub Pages Notes:

GitHub Pages supports a limited subset of Jekyll plugins. Other Jekyll plugin’s cannot be enabled (for security reasons).
GitHub Pages supports a number of extensions to Markdown called GitHub Flavored Markdown, however not all features seem to work properly.
Some repository metadata can be accessed.
Javascript can be used to generate/manipulate content.
A 3rd party GUI called prose.io can be used to develop content (currently disabled for security reasons).

How GitHub, Jekyll, Liquid and Kramdown all work.

User pushes changes to master branch of sstsimulator.github.io repository.
GitHub pages will automatically run the Jekyll processor on the committed files.
1. Run source files through Liquid and perform appropriate operations on tags, filters and templates. Store results into working file.
2. Run working files through Kramdown processor and store all results into the _site subdirectory on the GitHub Pages web server.
3. The GitHub pages url sstsimulator.github.io is linked to the _site subdirectory

Major Areas of Design

Directory structure of sstsimulator.github.io

/ - Root directory, contains the config.yml, index.html, sstpublications.bib and other support files.
- /_includes - Include directory, any files that are to be included as part of other pages.
- /_layouts - Any layout files go here.
- /_posts - SST Announcments go here. File format is YYYY-MM-DD-titleofpost.
- /_site - Generated web site. Wiped out and regenerated automatically when source file change.
- /img - Any common web site image files go here (buttons, logos, icons, etc).
- /js - All Javascript files go here.
- /SSTAttachments - Any small SST specific support files for users.
- /SSTAtticPages - Move obsolete pages here. They will still be accessible.
- /SSTDoxygen - Location of the Doxygen pages created for SST Releases and nightly builds.
- /SSTImages - SST specific image files go here.
- /SSTPages - All SST content pages go here
- /stylesheets - The web site stylesheets go here.

Content Pages

The /SSTPages directory contains the majority of the content used for the website.

All of the pages should have a defined prefix as part of its filename:

Release and Build documentation
- SSTBuildAndInstall - How to build and install SST releases.
- SSTUserBuildAndInstall - How to setup users machines for SST builds.
- SSTmicroRelease - Release Info.
SST Elements, Core and Tool information
- SSTCore - SST Core info.
- SSTElement - SST Elements info.
- SSTTool - SST Tools info.
Design and Developer information
- SSTDesign - Info on SST design information.
- SSTDeveloper - Info for SST developers.
- SSTPM - Info for SST Program Management.
- SSTTutorial - SST tutorials.
- SSTValidation - SST validation info.
Top Level web site pages (these use include files to provide content)
- SSTMain - The main links on the side and top of the web site (Downloads, Documentation, Support, and Index page).
- SSTTop - Other top level pages. Normally used as part of the sidebar under the Documentation section.

The page SSTPages/SSTPMSSTWikiPages provides a full list of pages with these prefixes. The page SSTPages/SSTPMSSTAtticPages provides a full list of moved to the /SSTAtticPages directory.

In the /SSTPages directory, there is a TemplatePage.md file that can be used as a starting file for future pages.

Include files

There are two types of files in the /_includes directory. Support files and SST Document includes.

Support Includes

These files have Inc_Support as a prefix in their file names. These provide a number of support functions used in other pages.

SST Document Includes

These files have Inc_SSTDoc as a prefix in their file names. These files provide content related to SST that can be duplicated in multiple pages.

Announcements

The files included in the /_posts directory are treated by Jekyll as blog entries. SST is using them as an announcments page (blogging is a possible future feature).

The main index page for the website has some scripts to scan the /_posts directory and display the latest posts. Additionally, there is a page to see all announcments by month/year.

Downloads

All downloads for SST are stored in the sstsimulator/sst-downloads repository. There are two tags for the releases (SSTReleases and SupportFiles). The tags should be edited and any additional files should be added as necessary to the tag.

The Downloads page should contain links to files in the above repository.

Doxygen

Doxygen for SST Releases and Nightly builds will be commited to the appropriate directories in /SSTDoxygen.

JavaScript

All Javascript code will be stored in the /js directory.

The following scripts are available:

jquery-1.11.3.js - This is a generic JavaScript API available for other scripts to use.
jekyll-search.js - This is the script that executes the site search function on the left sidebar.
bibtex_js.js - This is the script that converts a BibTex file into usable HTML.

Publications

Using the bibtex_js.js JavaScript, the sstpublications.bib file (located in the root of the repository) is converted into an html publications page. This conversion is done on the fly after the page loads.

Layout and Stylesheet

A modified version of the Sinorcaish stylesheet (in /stylesheets directory) is used to provide look and feel structure to the web site.

All markdown and html pages in the website will be rendered with the default.html (in /_layouts directory) page as the baseline template for all pages. This default.html works with the Sinorcaish stylesheet to implement the top bar, side bar and footers of the webpages.

Changes to either the Sinorcaish stylesheet or the default.html file will have global effects on the entire web site.

How to Develop and Test

As stated above, any commit to the master branch of the sstsimulator/sstsimulator.github.io repository will cause the site to rebuild with the new content. There are 2 main ways to make changes to the web site.

Quick and Dirty change

Using GitHub’s Web interface (or a cloned repository). Manually change and commit the file back to the repository.
This method provides no visual feedback that the change is correct before the commit.

Significant content Development

Follow the instructions on how to install Jekyll (and support Gems)
- Quick and Easy
  - $ gem install --user-install bundler jekyll
  - $ gem 'github-pages' - Quick and easy installation (Must have Ruby Installed)
- Multiple Detailed Instructions
Clone the sstsimulator/sstsimulator.github.io repository
Change directory to the cloned repository.
Run Jekyll in server mode
- bundle exec jekyll serve --incremental -OR- jekyll serve --incremental
  - Jekyll will build the website and host it on your workstation.
  - Any changes to files will cause Jekyll to re-build the web site.
  - Local versions of pages can be viewed at http://localhost:4000/ (this is the index page of the website).
  - the –incremental can be omitted to get a clean rebuild.
General comments
- Occasionally, Jekyll will fail to build due to syntax errors. Warnings do not include line numbers so it can be difficult to track the offending text down.
- Only UTF-8 is supported, if a non-UTF8 file is encountered, Jekyll will not build the file (very fustrating to find).
- This site is not a Wiki. There is no graphical editor, or wysiwyg preview.
  - You can go to the sstsimulator/sstsimulator.github.io, and look at individual pages to see a rendered image (not all features will work this way)

MacOS Instructions
- Install Xcode Command Line Tools
  - xcode-select --install
- Install Homebrew
  - $ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  - $ brew install ruby
- Modify $PATH in $HOME/.bash_profile
  - export PATH="/usr/local/opt/ruby/bin:/Users/auser/.gem/ruby/2.6.0/bin:$PATH"
- Install bundler and jekyll in user’s local directory, then github-pages.
  - $ gem install --user-install bundler jekyll
  - $ gem 'github-pages'
- Obtain a Github personal access token (OPTIONAL)
  - Visit Github and create a personal access token with public_repo scope, and download it
  - Assign the text contents of the token to the JEKYLL_GITHUB_TOKEN environment variable
    - $ export JEKYLL_GITHUB_TOKEN=`cat /Users/jwilso/Documents/github.token`
  - Configure browser to allow connections to ephemeral ports (49152 to 65535) on localhost.
  - Render and serve locally
    - $ cd <jekyll development root>
    - $ bundle exec jekyll serve
  - In browser, visit http://127.0.0.1/4000