/mulesoft-docs

Main MuleSoft documentation repository

Primary LanguageHTML

MuleSoft Documentation Repository

This is the repository for MuleSoft’s documentation and contains the source content for the docs site.

Community Contributions

MuleSoft welcomes contributions from the community! You can contribute or provide feedback for our documentation in the following ways:

  • Fork this repository, make edits, and submit a pull request. We respond to your request as quickly as possible.

  • File an issue. Be as specific as possible about the changes you’d like to see.

  • While viewing a page on our docs site, you can rate a specific topic and include comments for fixes, suggestions, or general feedback.

  • Send mail to the docs team: documentation@mulesoft.com

  • See the MuleSoft Docs Style Guide for writing tips.

Accepting the Contributor’s Agreement

Before you can contribute to our documentation, you need to complete two steps to acknowledge that you’ve read and accepted our Contributor’s Agreement:

  1. Review the agreement, which is available here.

  2. After you’ve read and agree to the agreement, you need to fill out the MuleSoft Contributor’s Agreement form and submit it to us. This form exists as an API notebook and does two things:

    • Identifies you using your GitHub account, and

    • Records your name as a contributor

After you’ve submitted the form, you are asked to authenticate to GitHub and accept our Contributor’s Agreement. When the script completes, an Issue is created in our contributor’s project with your name.

That’s it! You’re now able to make contributions to our documentation. Ready to get started?

Making a Contribution

After you accept our Contributor’s Agreement, you can simply fork our documentation repository and make changes, then submit a pull request.

Alternatively, you can click the Edit on GitHub link at the top of a page, click the pencil icon, and make your change.

The pull request is reviewed by our team as soon as possible.

Building the Site for Local Preview

This repository includes a Gradle build script that you can use to build the documentation site for local preview. The script automates all aspects of the build. All you need on your machine to execute the build is a Java Development Kit (aka java and javac).

Begin by cloning the documentation repository:

$ git clone git@github.com:mulesoft/mulesoft-docs.git
💡

If you’re not interested in the entire history, and you want to reduce the size of the clone, add the --depth flag to execute a shallow clone:

$ git clone --depth 1 git@github.com:mulesoft/mulesoft-docs.git

Next, switch to the directory into which you cloned the repository:

$ cd mulesoft-docs

Finally, use the gradlew command to launch Gradle and execute the site builder:

$ ./gradlew

Running gradlew with no arguments executes the default task, which is named build. It’s equivalent to the following:

$ ./gradlew build

(The build task may take several minutes to complete).

Once you’ve built the site, you can once again use Gradle to serve the site using a local, in-memory web server:

$ ./gradlew serve

You can now access the site from your browser at the location http://localhost:8000.

🔥
 Currently, not all links work in the local preview since the preview server doesn’t implement the rewrite rules used in production. If you encounter a 404 when clicking on a link in the site navigation, try adding ".html" to the URL in the location bar.

When you want to stop the preview server, simply press Ctrl+c.

To run a full build and launch the preview server in one shot, combine the build and serve tasks:

$ ./gradlew build serve

Building a Page for Local Preview

This repository includes a Gradle build script that you can use to build a documentation page for local preview.

./gradlew buildHtmlSingle -Pfile=<asciidoc-filepath>

Building the Site for Staging

The Gradle build script is also capable of building the site for staging and syncing the output to the staging server. The extra tasks and configuration needed for these operations are added when the profile property has the value staging. You can set this property by passing the flag -Pprofile=staging to the gradlew launch command.

To instruct Gradle to clean, build, and publish the staging site, execute the following command:

$ ./gradlew clean publish -Pprofile=staging
📎
 The staging site combines the assets from the staging branch of mule-docs-site-assets with the content from the master branch of mule-docs.

Building the Site for Production

The Gradle build script is also capable of building the site for production and publishing it to git. The extra tasks and configuration needed for these operations are added when the profile property has the value prod. You can set this property by passing the flag -Pprofile=prod to the gradlew launch command.

To instruct Gradle to clean, build, and publish the production site, execute the following command:

$ ./gradlew clean publish -Pprofile=prod
🔥
 The first time you execute this command, it will run for a very long time (depending on connection speed) since it must clone the publish (aka build output) repository anew.
💡
 To prevent the publish task from pushing the new commit to the remote repository, pass the flag -PdryRun to the gradlew launch command.

MuleSoft Docs Style Guide

The following sections describe the MuleSoft Docs publishing style.

Content

Style Correct Example Incorrect Example

Use active text instead of "will", "you’ll", "won’t", or "we’ll".

This feature initializes and merges your code.

This feature will initialize and merge your code.

Obfuscate login credentials in illustrations and code

The client secret is 4242424242424242-ABADDOG

My password is foobar123

Only use RFC-1918 IP addresses for example IPv4 addresses:
10.0.0.0 - 10.255.255.255 (10/8 prefix)
172.16.0.0 - 172.31.255.255 (172.16/12 prefix)
192.168.0.0 - 192.168.255.255 (192.168/16 prefix)

Set the server address to 10.1.1.42

For example, set the address to 42.42.42.42.

Use the example.com domain

For example, mydomain@example.com

Omit "please"

Contact MuleSoft Customer Support.

Please contact MuleSoft Customer Support.

Separate options with > and don’t cast the > in bold

File > New > Mule Project

File → New → Mule Project

Replace "in order to" with "to"

To start the procedure,

In order to start the procedure

Omit "then"

Click this and that

Click this, and then click that

Refer to variables in inline text as string literals

replayID

"replayID", replayID

Don’t use "select" if you mean click. Select only highlights text. Click activates a link or button.

Click OK.

Select OK.

Omit button ellipses

Click Test Connections.

Click Test Connections…​.

Omit "on" with click

Click Test Connections.

Click on Test Connections.

Init-cap words in headings

Default Value Setting

Default value setting

Spell out i.e. and e.g.

Create a connector, for example, for Salesforce

Create a connector, e.g. for Salesforce

Don’t put code examples in a screenshot

Put code in a source block

screenshot

Put a period outside a quote string

Don’t say "will".

Don’t say "will."

Use the Oxford comma

a, b, and c

a, b and c

Omit the trademark symbol

Anypoint Platform

Anypoint™ Platform™

AsciiDoc Conventions

  • The width of a table is 100% by default, so only specify a width (as a percentage value) if you want it to be 95% or less.

  • To specify the number of equal-width columns for a table, set the cols attribute to a number followed by an asterisk, such as [cols="3*"].

    🔥

    The value of the cols attribute should never be a string of repeating commas (e.g., cols=",,,").

    The only acceptable formats for the cols attribute value are (a) a single number followed by an asterisk (e.g., 3*) or (b) a comma-separated list of column specs (e.g., 1h,^2,>1).

  • To allow the column widths of a table to be automatically sized by the browser to fit the contents, add the autowidth option, such as [%autowidth,cols="3*"].

    • By default, adding the autowidth option makes the width of the table only as wide as the browser needs it to be.

    • To force the width of a table with auto-width columns to span the whole page, add the spread role, such as [%autowidth.spread,cols="3*"].

      📎
      		 Until further notice, the width attribute on a table is ignored when the autowidth option is used.

  • To apply explicit relative widths to a table’s columns, set the cols attribute to a comma-separated list of ratio values, such as [cols="1,2,1"] (which resolves to [cols="25%,50%,25%"]).

    • The column width percentages are calculated with a precision of up to 4 decimal places.

  • To apply a style to a column, add the letter corresponding to that style after the ratio value, such as [cols="1h,2,1"].

  • Only apply the a style to a column if it has complex content, such as lists or source blocks. For example, [cols="1,1a"].

    • If an isolated table cell has complex content (and not the whole column), add the a style directly to the cell, such as a|content here.

  • To give a table a header row, add the header option to the table, such as [%header,cols="3*"].

    • Option values are additive, so you can specify both the autowidth and header option using %header%autowidth.

    • A header row is implied if you put a blank line under the first row of the table in the AsciiDoc source.

  • The shorthand syntax for options (e.g., %autowidth), roles (e.g., .spread), and IDs (e.g., #anchor) must always be placed in the first positional argument of the block attribute line, such as [%header%autowidth.spread,cols="3*"].

  • Only add the source style to a listing block if you also specify a language (and want it to be syntax highlighted), such as [source,java].

  • Omit linenums option on 1 line code examples.

  • Put multi-word examples in a source block instead of a long tick marked string.

  • Tab names should be "Visual Studio Editor" and "XML Editor or Standalone".

  • Only XML or XML procedures can be in an XML tab. It’s illogical to put a screenshot in the XML tab.

  • Restrict tables to 2 or 3 columns - multi-column tables can be very difficult to read.

  • Wrap code example lines at spaces, or for Java after a dot. Code lines should be less than 60 characters, especially if you use the // <n> notation for callouts

  • Until Coderay fixes the spacing for line numbers, don’t reference code examples by line numbers. Instead use // <n> in the code example and reference the notation in the text below the code example.

  • Lists in the AsciiDoc source that use a bullet glyph (U+2022) as the marker are recognized as lists.

Lists

Rule Description Example

Imperative before lists

Before starting a list, provide a starting sentence that starts with "to" that describes the task you want people to provide. Also, don’t start a bullet or numbered list after a heading without a starting sentence.

To set the values:

Insert a period at the end of a sentence or bullet list item

Perform these tasks.

Perform these tasks

Start each item in a bullet list or numbered list with a capital letter

Start list items that are not reserved words with an init cap

  • Ensure all required fields are set.

Start number list items with an action

Number list items only start with an action such as Click, Set, etc.

  1. Click the plus sign to the right of Connector Configuration.

Font Changes

Font Description Example

Bold

A button or field name

Click Test Connections.

tick marks

Reserved words or code examples, such as a MEL expression

#[payload]

Italics

Emphasis

Ensure the checkbox is set

Bold italics

Mule Enterprise license requirements.

Enterprise

Bold links

Important links like Skip to Code

*\<\<Skip to Code>>*

Headings

  • No special characters in headings

  • Init-cap each word in a heading

  • Don’t put a colon at the end of a heading

  • Ensure headings are in order, h1 > h2 > h3 > h4. Don’t skip levels such as h2 > h5

  • Only one H1 per doc at the top of the file

  • Don’t number headings

Word Choices

  • JSON not Json

  • POJO not pojo or Pojo

  • MOJO not mojo or Mojo

  • ID not id or Id

  • Anypoint Studio not Mule Studio

Don’t spell out common acronyms such as POJO, JSON, MOJO, REST, SOAP, MQ, UI, IT, IP, TCP/IP