Formatting tricks for increased readability

General information
1

This post provides a summary of a few general formatting features you can use to write nice and well-structured posts in our community forum.

To start a new paragraph, just leave an empty line in between (i.e., just hit “Enter” twice!), like I now just did between the previous sentence and the current one.

You can use so-called “markdown” code in your posts: certain (sequences) of characters will automatically turn into formatting features. If you’re unsure, always check the preview of your post as you’re typing it (by default shown on the right of the editing field). For instance, you can put text in between certain numbers of asterisks like this:

In this sentence, I used text *in between asterisks*, some other text **in between double asterisks**, and finally some text ***in between triple asterisks***, which resulted in *italic*, **bold** and ***bold & italic*** output.

…and it will show up in your post like this:

In this sentence, I used text in between asterisks, some other text in between double asterisks, and finally some text in between triple asterisks, which resulted in italic, bold and bold & italic output.

You can also easily create bullet lists by typing:

- An item preceded by a dash
- Another item
- Yet another one

…and it will show up in your post like this:

  • An item preceded by a dash
  • Another item
  • Yet another one

Numbered lists are equally easy:

1. An item preceded by a number and a dot
2. Another numbered item
3. A final one

…will show up in your post like this:

  1. An item preceded by a number and a dot
  2. Another numbered item
  3. A final one

Linking to an online URL can be achieved as follows:

In this sentence I provide a link to the [MRtrix3 repository](https://github.com/MRtrix3/mrtrix3) for you to click on.

…will show up in your post like this:

In this sentence I provide a link to the MRtrix3 repository for you to click on.

Showing off an image somewhere else on the web can be done by:

Here is an impression of our idol: ![Image](http://community.mrtrix.org/user_avatar/community.mrtrix.org/jdtournier/120/9_1.png)

…which will have the following glorious results:

Here is an impression of our idol: Image

The subtle horizontal lines separating certain sections (that you might have spotted throughout this post) were achieved by putting three dashes on a single line making sure there’s an empty line before and after them as well.

In a reply to this post (see below), I will describe 2 slightly more advanced features that are particularly useful for our community.

1 Like
2

When you have to post big amounts of text for some reason, and you don’t want to have these cluttering up the rest of your post, you can use the following construction:

[details=Here goes something I wanted to share]
Here goes my lengthy text.
[/details]

The actual lengthy text will be hidden (collapsed) by default, and anyone reading your post can click on the description line to unfold it in place. This is how such a construction might appear, with an actual lengthier text:

Click here to reveal a poem I wanted to share with the community

Falling Stars

I am a falling star, burning up in the ionosphere,
all of my many lives
flashing through my mind at once -
not experienced in a linear sequence,
but opening up in an all-encompassing bloom.
Time blossoms.

-Time-

A million years ago,
I shared the apple,
hypnotized by the seeds
connecting into a pentacle;
a star shining in the fruit’s pulpy flesh.

I am a falling star, burning up in the stratosphere,
on a collision course
defined by fate or destiny.
Please make a wish upon me,
so that my life wasn’t lived in vain -
the fear of an insignificant life,
without a solid meaning to its end.

With juice sluicing down my chin,
I knew the consequences
of nearly all my actions.
Naivety turned into shame,
pushed me up, high into the sky,
a trade-off for my stubborn rebellions -
I was able to touch the heavens,
only to brace myself
against the steep ride back down.

I am a shooting star, disintegrating in the atmosphere.
Please make a wish upon me,
before I become too small to see.
Please make a wish upon me,
and benefit from my final breath,
so that I do not completely disappear
with this all-consuming fear,
of an end, lacking solid meaning.

Starlight/ Shooting star so bright,
falling star, you see burning up in fright,
I wish you may, I wish you might,
have the wish, you wish for, tonight.

Copyright 2016, Chris D. Aechtner

While this might appear handy to post scripts, logs or debug output from commands, there’s an even better way of doing that. In-line “code” style text can be surrounded by single backticks, while whole blocks can be surrounded by triple ticks, like this:

I just ran `mrview` with the `-version` option, and the first two lines of output were:
```
== mrview new_syntax-1325-gb16aa1c1 ==
64 bit release version, built Jan 25 2016, using Eigen 3.2.0
```

…which will result in:

I just ran mrview with the -version option, and the first two lines of output were:

== mrview new_syntax-1325-gb16aa1c1 ==
64 bit release version, built Jan 25 2016, using Eigen 3.2.0

Note this could also have been achieved by indenting the code section with 4 spaces (this is actually what the </> button on the editing toolbar does for you):

I just ran `mrview` with the `-version` option, and the first two lines of output were:

    == mrview new_syntax-1325-gb16aa1c1 ==
    64 bit release version, built Jan 25 2016, using Eigen 3.2.0

Notice how I actually used these techniques throughout my posts to show you how to achieve all this formatting. The advantage of the code tags is that any text in between them will not (accidentally) be interpreted as markdown code. The text just stays unaffected! Also, don’t be afraid to post long logs or anything like that: beyond a certain length, it will automatically appear in a box with a scrollbar. No risk of cluttering. :slight_smile:

In a final reply below, I will briefly explain how you can quote other peoples’ writings.

1 Like
3

The above is a quote of myself from the previous reply. To get this, I simply selected some text directly in that reply, and a “quote reply” button showed up next to it. When I clicked it, it automatically started a new reply, with some markdown text already in it, to take care of showing the quote. Even (at the same time) when you’re writing a reply, you can still interact with the original post and its replies (or for that matter, even with all the other posts if you browse to them; it won’t affect the reply you’re putting together!). You can even select other parts of the post and replies as you’re putting together your own reply, and have several quotes in your reply. I’ll now select another portion of my original post and quote it here:

Notice how readers can interact with a quote to, e.g., find out about the context in which it was originally mentioned.

That’s it for a basic starter’s guide. You can find more information about markdown code at this website, which also includes further links if you’re interested.

Enjoy the MRtrix community, and behave nicely! :smile: :thumbsup:

3 Likes
7

On the topic of quotes, the instructions above perform more “comprehensive” replies, in that they not only re-print the quoted text but also link to the originating post & author. It’s also possible to do “lazier” quotes with the “>” character:

> This *is* a quote.

This is *not* a quote.

produces:

This is a quote.

This is not a quote.

Just make sure to include a blank like in between the quoted vs. non-quote text! (If you forget to, Discourse adds the intended non-quoted text into the quoted text area)

These even stack if necessary:

> > Something person A said

> Person B disagreeing with person A

Person A disagreeing with person B's disagreement.

produces:

Something person A said

Person B disagreeing with person A

Person A disagreeing with person B’s disagreement.

But only use this approach if it’s necessary to extract specific text in order to contextualise the novel comment you are making; don’t needlessly add buckets of duplicate text into a thread.