Bullets Links and Headings - ccondra/merchdocs GitHub Wiki

Part 2: Contents

Step 1: Bulleted lists
Step 2: Relative links
Step 3: Absolute links
Step 4: Reference links
Step 5: Redirects
Step 6: Heading levels
Step 7: Anchors
Step 8: Linting rules
Step 9: Commit your changes

Tutorial

Step 1: Bulleted lists

The dotdigital Engagement Cloud topic begins with an introductory paragraph and a standard bulleted list with links.

Bulleted list

  1. From GitHub Desktop, open your branch in the editor.

  2. In the Explorer pane on the left, find the marketing/dotdigital folder and open the engagement-cloud.md file.

  3. Find the following code for the bulleted list.

    - [Chat with customers]({% link marketing/dotdigital/chat.md %})
- [Customize email campaigns][2]
- [Import contacts][3]
- [Add logic][4]
- [Automate campaigns][5]
- [Schedule campaigns][6]
- [Generate reports]({% link reports/customer-engagement.md %})

    In the merchdocs implementation of Markdown, a hyphen followed by one space represents a bullet. However, when working in the devdocs repository, a bullet must be followed by two spaces. In fact, merchdocs also accepts a double space after a bullet, as long as the same spacing is used for all bullets in the topic.

    Another rule about bulleted (unordered) lists is that there must be a blank line before and after the list. Each bullet at the root level starts at the beginning of the line. Thereafter, bulleted lists can be nested in any type of list. In the published topic, the bullet style changes from solid to open circle, and then to a square, depending on the indentation level.

Step 2: Relative links

Take a closer look at the links in the bulleted list. The first and last bullets are relative links to topics in the merchdocs repository. The link text is enclosed in square brackets, and the URL is enclosed in parentheses. For a relative link, the URL and path is enclosed with matching curly braces and percent signs. The word link is placeholder for the base URL, followed by a blank space and relative path to the file. The path for all relative links is described in relation to its position from the root of the src folder.

The following code creates a relative link to another file in the merchdocs repository.

[link text ]({% link path/filename.md %})

When working in the devdocs repository, the following format is required to create a relative link:

[link text ]({{ site.baseurl }}/path/filename.md)

Step 3: Absolute links

Absolute links are typically used for links that go outside the repository. The linked text is enclosed in square brackets, followed by the full URL enclosed in parentheses. By default, absolute links open in a new browser window or tab and have a small arrow icon after the link.

There are two simple building blocks for an absolute link:

[link text](url)

Here’s how an absolute link looks in Markdown:

[Adobe](https://www.adobe.com/)

Step 4: Reference links

A reference link uses a placeholder for the URL and refers to the full URL at the bottom of the section or topic. The list of reference URLs appears in the Markdown code, but is not included when the page is rendered as HTML. Reference links are the preferred link format because they are easy to read and can be used multiple times in a topic.

The bulleted list at the top of the page has six reference links that go to external absolute URLs, and three relative links that go to topics in the merchdocs repository.

In the list of references at the bottom of the topic, each item begins with the label enclosed in square brackets, followed by a colon, blank space, and the full URL without parentheses. The label can be either a number or text, and the list of reference URLs can be placed at the end of a section or at the bottom of the topic. Each entry in the list follows this format:

[label]: full_URL

The best way to show the value of reference links is to use them in a paragraph.

  1. Copy and paste the following sentence to your Markdown file.

    Engagement Cloud gives you the ability to produce professional, personalized communications.

  2. Copy and paste the following list of reference URLs below the sentence. (You might have to scroll to the right to capture all the text.) This example uses descriptive text as labels rather than numbers. Make sure to leave a blank line before and after the list.

    [logic]: https://support.dotdigital.com/hc/en-gb/articles/
[automate]: https://support.dotdigital.com/hc/en-gb/articles/212213998-Automated-and-triggered-campaigns-an-overview
[schedule]: https://support.dotdigital.com/hc/en-gb/articles/212213998-Automated-and-triggered-campaigns-an-overview

  3. To create easy inline links, simply type the label (enclosed in square brackets) into the text. These will become inline hyperlinks when the page is rendered. Update your sentence as follows:

    Engagement Cloud gives you the ability to add [logic], [automate], and [schedule] campaigns to produce professional, personalized 
communications.

    You can see how easy these links are to read.

Step 5: Redirects

VBEs who maintain their own content might occasionally need to redirect topics. Redirects are necessary whenever a topic is removed, moved, or renamed. A client-side redirect prevents users from getting a “404” (file doesn't exist) message if the link is no longer valid. Although client-side redirects can be managed individually in the metadata, server-side redirects are usually a better solution when multiple files are involved.

  1. Find the redirect in the metadata section at the top of the page.
    This client-side redirect was added because the file was moved to a different folder.

    ---
title: dotdigital Engagement Cloud
redirect_from:
 /marketing/engagement-cloud.html
---

  2. If you need help with redirects, don't hesitate to reach out to one of our team members for help.

Step 6: Heading levels

Our implementation of Markdown requires all headings to be properly nested using the basic heading levels 1, 2 and 3, and 4. Because the title in the metadata section at the top of the page is heading level 1, the first heading in any topic is always level 2. Heading level 2 begins with two hash marks (##) at the beginning of the line, followed by the heading text. In the same way, a heading level 3 begins with three hash marks (###) at the beginning of the line, followed by the heading text. And just as with bulleted lists, there must be a blank line before and after each heading.

We use sentence case for all heading text, which means that only the first word is capitalized. However, proper nouns like Magento are always capitalized, no matter where they appear. The title in the metadata is the exception to this rule. As heading level 1, the title is written in initial caps, which means that each main word is capitalized.

  1. Beginning on line 7, add the following level 2 headings and leave a blank line after each.

    ## Bulleted list
## Relative link
## Absolute link
## Reference link

  2. Find an example in the topic of the first three types of link. Then, copy and paste the code under the related heading. (You might have to adjust the indentation level of any bullets that you paste.)

  3. After the Reference link header, paste the following:

    Reference links are not rendered with the HTML.

  4. On the File menu, click Save.

Step 7: Anchors

Anchors are automatically generated from header text and converted to anchor IDs in lowercase characters and with hyphens for spaces. For example, a level 2 header ## Hello World is automatically assigned the anchor #hello-world.

Anchors can also be explicitly declared and placed at specific places on the page as link destinations. The anchor ID can be placed on a blank line anywhere in the topic. To explicitly declare an anchor-ID, type an open curly brace, followed by a colon, blank space, hash sign (#), anchor-id, and closing curly brace.

{: #my-anchor}

A link to the anchor can be placed inline with other text, or on a separate line. The linked text is enclosed in square brackets, followed by an open parenthesis, hash sign (#) and` anchor-id, followed by a closed parenthesis.

[linked text](#my-anchor)

  1. At the bottom of the page just before the list of reference links, add the following:

    {: #my-anchor}
This is my anchor destination.

    Make sure to leave a blank line before the previous bulleted list and one before the reference links that follow.)

  2. On line 6, press the Return key to create a blank line.

  3. Create a bulleted list of anchor links for each level 2 heading that you defined. For each item, use the anchor that was automatically generated from the heading.

  4. Add a fifth item for Anchor, that links to the anchor-id that you declared.

    - [Bulleted list](#bulleted-list)
- [Relative link](#relative-link)
- [Absolute link](#absolute-link)
- [Reference link](#reference-link)
- [Anchor](#my-anchor)

  5. Review your work and check for the following:

    • A blank line before and after each heading
    • A blank line before and after each bulleted list
    • A hash (#) sign at the beginning of each anchor-id
    • Trailing spaces (especially check the end of each line and the beginning of blank lines)

  6. Save the file.

Step 8: Linting rules

It's time to get out your feather duster! Our implementation of Markdown is governed by a set of rules that checks the format of the file against our list of requirements. These housekeeping rules – or linting rules as they are called – evolve over time. Occasionally a new rule is added, or an existing rule changed. After learning the basics, they’ll become second nature.

  1. In the main menu under Terminal, click New Terminal.

  2. To check for formatting errors, enter the following command in the terminal pane:

    rake check

    The format of your file is checked against each linting rule and listed in the terminal. If your file passes all tests, the message “no issues found” appears in green. If any issues are found, the line number and corresponding linting rule number are shown for each as follows:

    src/tutorial.md:43: MD009 Trailing spaces
src/tutorial.md:55: MD012 Multiple consecutive blank lines

  3. If issues are found, see if you can fix them and try again.

    rake check

  4. When your Markdown code passes the check, enter the following command in the terminal pane to generate a preview.

    rake

  5. If you get an error, scroll up in the terminal window and look for a red error message that indicates where the error occurred. Then, try to fix the error and try again.

  6. To display more detailed information, add a trace to the command, as follows:

    rake --trace

  7. When the preview of the Magento User Guide appears, go to Marketing > Communications.
    This output was generated from your local repository. Notice that the URL in the address bar includes the IP address of your local computer, rather than the user guide at docs.magento.com.

  8. After you have examined your work, return to the editor and close the Markdown file.

Step 9: Commit your changes

As a best practice, you should commit your work to your local branch at the end of each work session.

  1. Return to GitHub Desktop.
    The pane on the left lists each file that has been changed. The pane on the right highlights the lines with new content in green. The old version of any content that has been edited or deleted is shaded pink.


    Commit Changes

  2. On the Changes tab, the checkbox of each changed file is selected by default. If multiple files have changes, you can select one file at a time and enter a different description for each.

  3. At the bottom of the pane in the text box above the description, enter a heading for the type of changes that you made. For example, “Tutorial examples”.

  4. In the Description text box, briefly explain the changes. For example, “Added examples of bullets, links, and headers.”
    If this was an actual project, you might have updated several files.

  5. If needed, repeat this process to describe the changes to each file.

  6. When you are ready, click Commit to my-branch.

Congratulations! Two down, two to go!
Go to Part 3

⚠️ **GitHub.com Fallback** ⚠️