New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Example post demonstrating Markdown features #2

Open
susanBuck opened this Issue Jan 28, 2019 · 0 comments

Comments

Projects
None yet
1 participant
@susanBuck
Copy link
Owner

susanBuck commented Jan 28, 2019

When writing posts/replies here on the Issues forum, you should always use proper Markdown formatting. Carefully formatted posts are easier to parse resulting in quicker feedback and a more useful reference resource for the entire class.

In this post, I'm going to provide several examples of key Markdown features you should use when writing posts.

First, read the post as you see it here.

Then, read the "raw" version of the post here to see the underlying Markdown I used in each of the examples.

All of the techniques shown are covered in the guide Mastering Markdown which I'll prompt you to read at the start of the semester.

Block code

First, let's talk about code. Let's say you need to share this block of PHP code in a post:

if (isset($_GET['keyword'])) {
$keyword = $_GET['keyword'];
} else {
$keyword = '';
}

This code is hard to read because the indentation is lost, there's no syntax highlighting, and it's not written in a mono-spaced font which is optimal for displaying code.

Using Markdown code fences (three backticks before and after the code block) you can make the code look better:

if (isset($_GET['keyword'])) {
    $keyword = $_GET['keyword'];
} else {
    $keyword = '';
}

Even better though, you should include the language (in this case, php) as part of the starting backticks so that the code is also syntax highlighted:

if (isset($_GET['keyword'])) {
    $keyword = $_GET['keyword'];
} else {
    $keyword = '';
}

Code fences should also be used if sharing other code-like content such as the output of error logs or configuration files.

For example, here's the output of an error log without any formatting:

Wed Sep 13 20:41:29 2017] [notice] Graceful restart requested, doing restart
[Wed Sep 13 20:41:30 2017] [notice] Digest: generating secret for digest authentication ...
[Wed Sep 13 20:41:30 2017] [notice] Digest: done
[Wed Sep 13 20:41:30 2017] [notice] Apache/2.2.32 (Unix) mod_wsgi/3.5 Python/2.7.13 PHP/7.1.6 mod_ssl/2.2.32 OpenSSL/1.0.2j DAV/2 mod_fastcgi/2.4.6 mod_perl/2.0.9 Perl/v5.24.0 configured -- resuming normal operations

Compare the legibility of that to the same content using code fences:

[Wed Sep 13 20:41:29 2017] [notice] Graceful restart requested, doing restart
[Wed Sep 13 20:41:30 2017] [notice] Digest: generating secret for digest authentication ...
[Wed Sep 13 20:41:30 2017] [notice] Digest: done
[Wed Sep 13 20:41:30 2017] [notice] Apache/2.2.32 (Unix) mod_wsgi/3.5 Python/2.7.13 PHP/7.1.6 mod_ssl/2.2.32 OpenSSL/1.0.2j DAV/2 mod_fastcgi/2.4.6 mod_perl/2.0.9 Perl/v5.24.0 configured -- resuming normal operations

Inline code

If you need to include a smaller snippet of code inline with your text, use backticks (Markdown syntax for inline code). For example, let's say you believe the poster's problem is a missing closing div tag - use back tickets and write it as </div> to make the code mono-spaced and stand out from the rest of the paragraph.

This inline formatting should also be used for things like file names, paths, command line commands, etc.

For example, compare this paragraph with no code formatting...

If your SSH key was not added before creating your droplet, you have to manually add it. You can do this by running the command "cat id_rsa.pub | ssh root@[your.ip.address.here] "cat >> ~/.ssh/authorized_keys"" (be sure to replace with your IP address before running this). Once you do that, try SSH'ing ("ssh root@[your.ip.address.here]") into your server again.

...to that same paragraph where it's easy to pick out the commands and important bits:

If your SSH key was not added before creating your droplet, you have to manually add it. You can do this by running the command cat id_rsa.pub | ssh root@[your.ip.address.here] "cat >> ~/.ssh/authorized_keys" (be sure to replace with your IP address before running this). Once you do that, try SSH'ing (ssh root@[your.ip.address.here]) into your server again.

Other

  • Use bold text to highlight/emphasize key parts. For example, if you spend several paragraphs setting up a question, it would be useful to bold the sentence or two that contains the actual question.
  • When listing things, use a bulleted list rather than paragraph form.
  • Break lengthy paragraphs down into smaller, logical chunks that are easier to parse and skim.
  • Follow all the course guidelines on writing good posts under dwa15.com > Issues Forum > Getting help effectively
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment