Repository files navigation

The website for gem5 is written inJekyll markdown.It serves as the primarily source of information for those interested in thegem5 project. In the spirit of gem5's community-led, open governance modelanyone who wishes may make contributions and improvements to the website.This README outlines the basic procedure to do so, as well as notes thedirectory structure and general guidelines.

You may clone the repository, and run a local instance of the websiteusing:

git clone https://github.com/gem5/websitecd websitebundlejekyll serve --config _config.yml,_config_dev.yml

The jekyll server may also be run using:

bundle exec jekyll serve --config _config.yml,_config_dev.yml

Changes may be made and committed using:

git add <changed files>git commit

The commit message must adhere to our style. The first line of the commitis the "header".The header line must not exceed 65 characters and adequatelydescribe the change. To be consistent with commits made to the gem5 repository,the header should start with awebsite tag followed by a colon.

After this, a more detailed description of the commit can be included. This isinserted below the header, separated by an empty line. Including a descriptionis optional but strongly recommended for complex changes. The description mayspan multiple lines, and multiple paragraphs.No line in the descriptionmay exceed 72 characters. We also recommend adding reference to any relevantGitHub issue so the context of a change can be more easily understood.

Below is an example of how a gem5 website commit message should be formatted:

website: This is an example headerThis is a more detailed description of the commit. This can be as long asis necessary to adequately describe the change.A description may spawn multiple paragraphs if desired.Issue: https://github.com/gem5/gem5/issues/123

We utilize GitHub to review changes made to the website. To makechanges, follow the steps below.

1. Fork the gem5 repository on GitHub fromhttps://github.com/gem5/website/.
2. Create a new branch in your forked repository for your changes.
3. Commit your changes to the new branch.
4. Push the branch to your forked repository.
5. Open a pull request from your branch in your forked repository to the main gem5 website repository.

If you have not signed up for an account on the github(https://github.com/), you first have to create an account.

1. Go tohttps://github.com/
2. Click "Sign up" in the upper right corner.

Changes are required to have aChange-ID, which can be added using the pre-commithook. This can be installed via the following:

pip install pre-commitpre-commit install

The rule for when to work on the stable vs. develop branch is as follows:

• If the change applies to the current gem5 stable, then the change should be on the stable branch of the gem5 website.

• If the change cannot work on gem5 stable and requires updates to gem5 that are only found on gem5 develop, then the change should be on the develop branch of the website.

When a new version of gem5 is released, the develop branch is merged into the stable branch. When the website's stable and develop branches diverge, we merge stable into develop.

Once a change has been submitted to GitHub, you may view the change athttps://github.com/gem5/website/pulls.

Through the GitHub pull request we strongly advise you add reviewers to your change.GitHub will automatically notify those you assign. We recommend you add bothBobby R. Brucebbruce@ucdavis.edu (@BobbyRBruce) andJason Lowe-Powerjason@lowepower.com (@powerjg) as reviewers.

Reviewers will review the change. For non-trivial edits, it is not unusualfor a change to receive feedback from reviewers that they want incorporatedbefore flagging as acceptable for merging into the gem5 website repository.All communications between reviewers and contributors should be done in apolite manner. Rude and/or dismissive remarks will not be tolerated.

Once your change has been accepted by reviewers a maintainer will squash and merge your pull request into the gem5 website repository.into the gem5 website repository. The website will be automatically updatedwith your changes within 30 minutes.

Yaml files, for easily editing navigation.

Page section and main navigation bar are here.

Different layout templates used on the site.

• default: base layout
• page: any regular page
• toc: a page that requires table of contents
• post: blog post page
• documentation: documentation page

All pages (other than the index.html home page) should be placed in this folder. There is a subfolder /documentation where pages meant for the documentation part of the site can be kept. This is purely for organization and ease of finding things. Reorganizing the _pages folder should not affect the site.

Holds blog posts.

All custom css is kept in_layout.scss.

Images and javascript files.

Holds index.html of blog page.

To edit the navigation bar:Go to_includes/header.html

• Navigation element without submenu:

<liHome" %}active{% endif %}">  <a href="{{ "/" | prepend: site.baseurl }}">Home</a></li>

ReplaceHome in{% if page.title == "Home" %} to your page's title.Replace/ inhref="{{ "/" | prepend: site.baseurl }}" to the page's permalink.ReplaceHome in>Home</a> with what you want the navbar to show.

• Navigation element with submenu:

<liabout" %}active{% endif %}">  <a data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">    About  </a>  <div aria-labelledby="navbarDropdownMenuLink">    <a href="{{ "/about" | prepend: site.baseurl }}">About</a>    <a href="{{ "/publications" | prepend: site.baseurl }}">Publications</a>    <a href="{{ "/governance" | prepend: site.baseurl }}">Governance</a>  </div></li>

Replaceabout in{% if page.parent == "about" %} with a word that will represent the parent of all pages in the submenu. Make sure the frontmatter in those pages includes parent: [your_parent_identifier].Replace the permalink and title in all the<a></a> submenu items.

Parent Topic:

• subtopic
• subtopic
• ...

Parent Topic:

• subtopic
• ...

To edit the documentation navigation, simply edit thedocumentation.yml file in the_data folder.docs lists the parent topics, and within itsubitems lists its subtopics. This is an example of how it should be formatted:

title: Documentationdocs:  - title: Getting Started     # Parent Topic    id: gettingstarted     # see below    url: /gettingstarted     # see below    subitems:      - page: Introduction     # Name that will appear in navigation        url: /introduction     # url      - page: Dependencies        url: /dependencies  - title: Debugging     # Parent Topic    id: debugging     # see below    subitems:      - page: Piece 1        url: /piece1      - page: Piece 2        url: /piece2

Notes:id is an identifier that links subtopics to its parent. It is required and must not contain any spaces. The subtopic pages must include in the frontmatterparent: id withid being the parent'sid.

url is optional for parent topics, if a parent topic has its own a page. If nourl is provided, it will automatically link to the first subtopic.

To add a new documentation page, first add frontmatter at the top of either the markdown or html file to be added.

---layout: documentation     // specify page layouttitle: Getting Started     // title of the pageparent: gettingstarted     // see belowpermalink: /gettingstarted/     // url---

Notes:

parent should be the exact same as theid of its parent topic that is assigned to it in_data/documentation.yml file. (If the page is the parent topic,parent is the same as theid assigned to it in_data/documentation.yml file.)

Place the file in_pages/documentation. Make sure to add the page to the documentation navigation, explained by the section above.

To flag information in a page as valid, use an outdated notice in the.md file of that page:

{: .outdated-notice}This page is outdated!

This will be replaced by a warning element containing the text "Note: This page is outdated.", followed by the content succeeding the notice - in this case, "This page is outdated!". In this way, you can add additional information explaining why or how the page is outdated, and general tips on what to do to mitigate this issue.

Notes:

Make sure that the text following{: .outdated-notice} is not used as a title, heading, or any other important Markdown element, as it will be incorporated into the outdated notice and break formatting.

Add blog page to _posts folder.Page must be named in this format:yyyy-mm-dd-name-of-file.mdAt the top of the page add:

---layout: post     // specify page layouttitle: How to Debugauthor: Johndate: yyyy-mm-dd---