LaGriT Style Guide


In an effort to maintain consistency across the GitHub Pages implementation of LaGriT documentation, this document is a style guide (draft). Its use should be applied across all commands. See the ADDMESH page for an example of it applied.

Table of Contents

  1. Page Titles
  2. Command Formatting
  3. Inline Code
  4. Linking to Other Pages
  5. Formatting Metadata
  6. Further Resources

1. Page Titles & Headers

Page titles should use the h1 header class followed by a horizontal rule. This is accomplished in Markdown by:

# Page Title #
--------------------

Page Title


Subsections should be marked with h2, subsubsections with h3, etc.

# My Command #
--------------------

## 1. Usage ##
### 1.1 First Step ###
This is the first step to using this great command.

### 1.2 Second Step ###
This is the second step to using this command.

My Command


1. Usage

1.1 First Step

This is the first step to using this great command.

1.2 Second Step

This is the second step to using this command.

2. Command Formatting

When rendering LaGriT commands, it is the convention on the LANL website to use bold monospaced font for literal keywords and unstyled monospace for variable names, mesh objects, etc.

This is difficult to do in pure Markdown, but fortunately very easy to do in HTML. Since part of the Markdown specification includes embedded HTML parsing, LaGriT commands should be styled as:

<pre>
<b>addmesh / add</b> / mesh3 / mesh1 / mesh2 / [refine_factor] / [tet edge]
<b>addmesh / amr</b> / mesh3 / mesh1 / mesh2 /
<b>addmesh / append</b> / mesh3 / mesh1 / mesh2 /
</pre>
addmesh / add / mesh3 / mesh1 / mesh2 / [refine_factor] / [tet edge]
addmesh / amr / mesh3 / mesh1 / mesh2 /
addmesh / append / mesh3 / mesh1 / mesh2 /

Note how the block in enclosed in the <pre> tags.

3. Inline Code

Similarily to the section above, for sections(s) of code within a larger normally typed paragraph, literal keywords should be bold and all other objects should be unstyled. Mesh objects should be formatted with italic monospace.

Similar to merge except `imt`, `icr`, `itetclr` of *`mesh2`* have the value `max(imt(mesh1))` added to *`mesh2`*.

Similar to merge except imt, icr, itetclr of mesh2 have the value max(imt(mesh1)) added to mesh2.

4. Linking to Other Pages

You can link to other pages on this site by either using the literal URL, or (more appropriately) with a relative link to the corresponding Markdown file. It is better practice to use a relative link to a Markdown file, so that those attempting to read the documentation through a Markdown viewer (i.e. after cloning the LaGriT repo) will be able to easily access the referenced document.

As an example, [this page](https://lanl.github.io/LaGriT/pages/docs/commands/ADDMESH.html)
will take you to the same place as [clicking here](docs/commands/ADDMESH.md).

As an example, this page will take you to the same place as clicking here.

5. Formatting Metadata

Each page should contain YAML-formatted metadata at the top of the document. See GitHub’s announcement and a basic guide on supported tags.

In general, most metadata will do nothing. However, each document should contain at least these specifiers:

  1. title - this renders as the browser page title, and renders in search
  2. tags - this benefits the search functionality as well
---
title: "Example LaGriT Page"
author: My Name
tags: example, quickstart
---

6. Miscellaneous

6.1 Inline Text Formatting

This is **bold**, *italics*, ~~strikthrough~~, and `code`.
You can stack these, like:
**`bold code`**, *`italic code`*, ~~`strikethrough_code`~~.
This is bold, italics, strikthrough, and code. You can stack these, like: **`bold code`**, *`italic code`*

6.2 Embedding Images


Below are multiple ways to embed images in a Markdown file.
Note that relative paths are relative to LaGriT/docs/pages/docs/commands/.

<img width="500" src="https://lanl.github.io/LaGriT/assets/images/sphere_cube_colors26_expand.png">
![alternate text](https://lanl.github.io/LaGriT/assets/images/sphere_cube_colors26_expand.png)
<img src="{{'assets/images/sphere_cube_colors26_expand.png' | absolute_url}}" width="500">
![alternate text](../../../assets/images/sphere_cube_colors26_expand.png)
![alternate text]({{ site.baseurl }}/assets/images/sphere_cube_colors26_expand.png)
![alternate text]({{'assets/images/sphere_cube_colors26_expand.png' | absolute_url}})

7. Further Resources

Markdown supports tables, lists, embedded HTML/Javascript/CSS, images, and more. For syntax usage on embedding these elements, a few references can be found below: