How to format posts, including math and code

forum-howto
Tags: #<Tag:0x00007f7f785646a0>

(Jonathan Sick) #1

You can format posts to community.lsst.org using Markdown or HTML. Math expressions can even be typeset using standard LaTeX notation.

Much of the formatting can be done with the toolbar at the top of every editing window, but if you’re interested in learning how to format with simple markup, read on.

Markdown Basics

Headers

You can can organize your post into sections by creating headers. Simply prepend the section title with #, and repeat the # character to signify the level of the heading. For example, the headers here were written as

## Markdown Basics

### Headers

For posts we recommend you start with a Level 2 header, i.e., ## Title. The Level 1 header is effectively the topic’s title.

Emphasis

Add nuance to your writing with italic (created via *italics*) and bold (`bold``) typefaces.

Links

You can write links using Markdown’s [text](url) syntax. For example, LSST DM was written as [LSST DM](http://dm.lsst.org).

The forum will also automatically hyperlink any text that can be interpreted as a URL, for example: http://dm.lsst.org.

Tip: If you link to another post on this forum, that topic’s title will appear in the sidebar of your post.

Lists

Create bullet lists by prepending - or * to each item. For example:

- item one
- item two

renders as

  • item one
  • item two

Numbered lists can created by prepending each line with the item number and a period. For example:

1. item one
2. item two

renders as

  1. item one
  2. item two

You can create sub-lists by indenting three spaces relative to the parent list and adding a line between each item. For example:

1. Item one

2. Item two

   * foo
   * bar

3. Item three

renders into:

  1. Item one

  2. Item two

    • foo
    • bar
  3. Item three

Code snippets

You can write inline code snippets and other pre-formatted text using the back tick delimiter (`). For example, `import lsst` renders as import lsst.

To include blocks of code, surround the section with a GitHub-style ‘code fence’ consisting of three back ticks before and after the code. For example,

```
import numpy as np
import lsst
```

renders as

import numpy as np
import lsst

The forum will try to guess what programming language you’re writing and highlight that code. If you need to override that, add the language’s name after the first set of back ticks. For example:

```python
import numpy as np
import lsst
```

Support languages include: bash, cpp, diff, xml, http, json, java, javascript, makefile, markdown, ruby, perl, python, sql. Use text to disable highlighting.

Tables

Our Discourse platform doesn’t support GitHub Flavored Markdown-style tables at the moment.

In the meantime, you can create plaintext tables with code fences and the ‘text’ tag (see above). Consider using the GitHub Flavoured Markdown table syntax to be future-proof.

If you’re particularly ambitious, you can also markup your table in HTML.

Images

Just drag-and-drop images from your filesystem onto the editor window. This will upload the image to the community.lsst.org server and add the appropriate markup to your post.

Writing Math in LaTeX

community.lsst.org uses MathJax to render mathematical expressions in the browser using the LaTeX markup you already know and love.

Inline Math Expressions

To write an inline expression, just enclose the LaTeX markup with single dollar signs ($).

For example, $m = -2.5 \log_{10}(F)$ renders into $m = -2.5 \log_{10}(F)$.

Display Math

To make an expression render onto its own line (i.e., display math), enclose the expression in double dollar signs ($$).

For example, $$\ln\,p(y\,|\,x,\sigma,m,b,f) = -\frac{1}{2} \sum_n \left[ \frac{(y_n-m\,x_n-b)^2}{s_n^2} + \ln \left ( 2\pi\,s_n^2 \right ) \right]$$ renders as $$\ln,p(y,|,x,\sigma,m,b,f) = -\frac{1}{2} \sum_n \left[ \frac{(y_n-m,x_n-b)^2}{s_n^2} + \ln \left ( 2\pi,s_n^2 \right ) \right]$$

Tip: with the $$ delimiter, you don’t have use type newlines for the expression to appear on its own line.

(Hat tip to Dan Foreman-Mackey for this likelihood function example.)

Multiple Equations

If you have multiple equations and would like to align them, use the align environment. For example,

\begin{align}
\nabla \cdot \bf{E} & = \frac{\phi}{\epsilon_0} \\
\nabla \cdot \bf{B} & = 0 \\
\nabla \times \bf{E} & = -\frac{\partial \bf{B}}{\partial t} \\
\nabla \times \bf{B} & = \mu_0 \left( \bf{J} + \epsilon_0 \frac{\partial \bf{E}}{\partial t}  \right)
\end{align}

renders as

\begin{align}
\nabla \cdot \bf{E} & = \frac{\phi}{\epsilon_0} \
\nabla \cdot \bf{B} & = 0 \
\nabla \times \bf{E} & = -\frac{\partial \bf{B}}{\partial t} \
\nabla \times \bf{B} & = \mu_0 \left( \bf{J} + \epsilon_0 \frac{\partial \bf{E}}{\partial t} \right)
\end{align}


Learn more about using the LSST Community forum →


About the Sims Announcements category
About the EPO category
About the Science category
About the LSST2016 category
About the DM IN2P3 category
About the LSST2017 category
Is scons used by lsstsw to install third-party lightly-warpped packages?
About the Data Q&A category
About the LSST2018 category
Welcome to community.lsst.org
About the Support category
About the Data Management category
About the DM Notifications category
About the Simulations category
About the Camera category
About the Camera-DM Visualization category
About the Meta category
(Jonathan Sick) #2

2 posts were split to a new topic: Markdown or restructuredText for DM?