Code Snippets

You can create and insert code into documentation in dozens of languages. The syntax is automatically highlighted according to the language, similar to text editors such as Sublime Text and Notepad++. In HTML5 output, users can click a Copy button, then paste the code into a third-party editor.

How to Create and Insert Code Snippets

  1. Place your cursor in an empty paragraph.
  2. Select Insert > Code Snippet.
  3. On the left side of the Code Editor, enter or paste code.
  4. (Optional) On the right side of the editor, complete any of the options.
    • Caption Enter a caption (or title) for the code snippet.
      • Position Select whether to place the caption above or below the code.

      • Repeat If you select "Repeat," the caption will be displayed where page breaks are encountered in print-based output (except Microsoft Word).

    • Language Select the code language. The code will be formatted appropriately, with syntax highlighting.

      If you select "(inherit)," the code uses whichever language is selected for the MadCap|codeSnippetBody style (the default setting is "PlainText"). So if you change the setting to a specific language, that language will automatically be used when you first insert a new code snippet. You can also create classes of that style and assign different languages to those classes. See Editing the Styles for Code Snippets.

      Example In your stylesheet, you create a class of the style MadCap|codeSnippetBody, naming it "CSS." Then you create another class and name it "JavaScript."

      On the "CSS" class you set the mc-code-lang property to CSS.

      And on the "JavaScript" class, you set the mc-code-lang property to JavaScript.

      When you insert a new code snippet containing CSS, you leave the Language field set to (inherit). Initially, the code displays as plain text. But after you apply the CSS style class to MadCap|codeSnippetBody, the syntax highlighting automatically changes to show the formatting appropriate for CSS.

      You insert another snippet containing JavaScript. This time you apply the JavaScript style class to MadCap|codeSnippetBody. The syntax highlighting changes for formatting appropriate for JavaScript.

    • Line Numbers Select this to include line numbers to the left of each line of code.

      • Starting Number Enter the number for the first line of code shown.

      • Continuous Select this if you are inserting multiple code snippets with line numbers, and you want the numbering to continue from one code snippet to the other, rather than starting over.

      Note If you enter a starting number and select Continuous, the number entered in the first field is ignored. The continuous setting has precedence.

  5. Click OK.
  6. Click to save your work.

How to Edit the Content for Code Snippets

  1. Right-click the code snippet where it has been inserted, then select Edit Code Snippet.
  2. In the Code Editor, you can change the text on the left side. You can also adjust any of the fields on the right side. For details of the fields, see Creating and Inserting Code Snippets.
  3. Click OK.
  4. Click to save your work.

How to Edit the Styles for Code Snippets

  1. Open the stylesheet that you want to modify.
  2. In the local toolbar, make sure the first button displays . If the button displays instead, then click it.
  3. In the upper-left of the editor, make sure the drop-down field is set to .
  4. On the left side of the editor, find and select one of the following styles, depending on what you want to accomplish.
    • MadCap|codeSnippet This controls the look of the entire code snippet block. Common changes you might make to this style are the border, background, or padding.

    • MadCap|codeSnippetBody This controls the look of the code text, as well as the line numbers and vertical border to the right of the numbers. Modifying most properties is straightforward; however, if you want the numbers to be different from the rest of the text (online outputs only), you might need to create a complex (or advanced) selector called "pre span" and change the properties for that.

    • MadCap|codeSnippetCaption This controls the look of the caption used for the code snippet.

    • MadCap|codeSnippetCopyButton This controls the look of the copy button link that can be added to code snippets for HTML5 output. If you want to change the word "Copy" to something else, you can edit the mc-label property.

  5. From the Show drop-down list on the upper-right side of the editor, select . The most relevant properties for that style are shown on the right side of the editor.

  6. (Optional) You can use the toggle button in the local toolbar to show properties below in a group view or an alphabetical view .
  7. Locate the property you want to change.

    There are a couple of MadCap-specific properties that are particularly relevant when editing the look of code snippets:

    • mc-code-border Lets you control the look of the vertical border to the right of the numbers (if they are included) in a code snippet. Typically, this would be associated with the MadCap|codeSnippetBody style, or a class of it.
    • mc-code-lang Lets you select the coding language to be used by default with the associated style. Typically, this would be associated with the MadCap|codeSnippetBody style, or a class of it.
  8. The area to the right of the property is used for selecting and entering values. If you know how to enter the information correctly, you can click in the value field and type it directly. Otherwise, click the ellipsis button to the right of the property. Depending on the type of property, the appropriate controls and options display, allowing you to choose or enter values (e.g., select from a drop-down list, click a button, complete fields in a dialog or popup). If you completed values in a popup, click OK at the bottom of the box.

    Note If you switch the Show drop-down list to another filter (e.g., Show: All Properties), you can edit additional properties.

  9. Click to save your work.