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: [email protected]

• 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 [email protected]:mulesoft/mulesoft-docs.git

Tip	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 [email protected]: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 to execute the site builder:

$ ./gradlew build

The build task may take several minutes to complete.

Once you have built the site, you can once again use Gradle to serve it through a local, in-memory web server:

$ ./gradlew serve

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

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

Caution

At the moment, not all links will work in the site since the preview server doesn’t implement any of the rewrite rules that are used by the production site.

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 ci. You can set this property by passing the flag -Pprofile=ci to the gradlew launch command.

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

$ ./gradlew clean publish -Pprofile=ci

Caution

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.

Warning

The publish task doesn’t yet push the new commit to the remote repository.

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, [email protected]	[email protected]
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
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

• [source] is better than [source,code].

• Better to use "a" columns in tables such as cols="30a,70a".

• 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 usee \//<1> in the code example and reference the notation in the text below the code example.

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.	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