This is the repository for MuleSoft’s documentation and contains the source content for the docs site.
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.
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:
-
Review the agreement, which is available here.
-
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?
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.
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
💡
|
If you’re not interested in the entire history, and you want to reduce the size of the clone, add the $ 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 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>
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. |
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.
|
The following sections describe the MuleSoft Docs publishing style.
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: |
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] |
|
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 |
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™ |
-
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 asa|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
andheader
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.
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 |
|
Start number list items with an action |
Number list items only start with an action such as Click, Set, etc. |
|
Font | Description | Example |
---|---|---|
Bold |
A button or field name |
Click Test Connections. |
|
Reserved words or code examples, such as a MEL expression |
|
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>>* |
-
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