Markdown Cheatsheet
Markdown formatting is simple, and the CFEngine generator adds a few things to make it even simpler. Here's a list of the most commonly used formats.
Basic Formatting
One
Paragraph
Two
Paragraphs
One Paragraph
Two Paragraphs
**Bold**
Bold
*Italic*
Italic
Links
Link within documentation and to known pages
You can link to any documentation page section using [linktext][PageTitle#optional section]
.
For example I can link to collecting functions using [collecting functions][Functions#collecting functions]
.
[top of the page][Markdown Cheatsheet], to the [Markdown Cheatsheet][], [inside page][Markdown Cheatsheet#Links] and [inside current page][Markdown Cheatsheet#Links]
top of the page, to the Markdown Cheatsheet, inside page and inside current page
Note: For known pages, see the _references.md file.
Link to CFEngine keyword
The documentation pre-processor will create those automatically.
`classes` and `readfile()`
classes
and readfile()
However, the preprocess will not create links if the code word is in triple backticks:
```classes``` and ```readfile()```
classes
and readfile()
Link to External URL
[Markdown Documentation](http://daringfireball.net/projects/markdown/)
Lists
Unordered lists - Markdown supports other markers than the asterisk, but in
CFEngine we use only *
.
* Item 1
* Item 2
* Item 2a
* Multi paragraph item
Four spaces indented
- Item 1
- Item 2
- Item 2a
Multi paragraph item
Four spaces indented
Ordered lists - the numbers you use don't matter.
1. first
1. second
9. Third
- first
- second
- Third
Tables
Wiki-syntax for tables is supported, and you can be a bit sloppy
about it, although it's better to align the |
properly.
| Header | Left aligned | Centered | Right aligned |
|--------|:-------------|:--------:|--------------:|
|text | text | X | 234 |
Header | Left aligned | Centered | Right aligned |
---|---|---|---|
text | text | X | 234 |
Code
Inline code
This renders as `inline code`.
This renders as inline code
.
This also renders as ```inline code```.
This also renders as inline code
.
See the note above on implicit linking - single backticks will link, triple backticks won't.
Code Blocks
Code blocks are either indendented by four spaces:
Just indent by four spaces:
$ code block
$ without syntax highlighting
$ code block
$ without syntax highlighting
or use three backticks:
```
some more code
in a block
```
some more code
in a block
To turn on syntax highlighting, specify the brush directly after the opening three backticks. Syntax highlighting is provided by pygments. Find all available lexers here.
CFEngine Code Blocks
If you want CFEngine syntax highlighting, use
```cf3
# CFEngine block
bundle agent example()
{
}
```
# CFEngine code block
bundle agent example()
{
}
Other frequently used syntax highlighers shown below.
Bash Script Code Blocks
```bash
#!/bin/bash
echo hi
for i in `seq 1 10`;
do
echo $i
done
```
#!/bin/bash
echo hi
for i in `seq 1 10`;
do
echo $i
done
Console Blocks
```console
root@policy_server # /etc/init.d/cfengine3 stop
```
root@policy_server # /etc/init.d/cfengine3 stop
SQL Code Blocks
```sql
SELECT
FileChanges.FileName,
Count(Distinct(FileChanges.HostKey)) AS DistinctHostCount,
COUNT(1) AS ChangeCount
FROM
FileChanges JOIN Contexts
WHERE
Contexts.ContextName='ubuntu'
GROUP BY
FileChanges.FileName
ORDER BY
ChangeCount DESC
```
SELECT
FileChanges.FileName,
Count(Distinct(FileChanges.HostKey)) AS DistinctHostCount,
COUNT(1) AS ChangeCount
FROM
FileChanges JOIN Contexts
WHERE
Contexts.ContextName='ubuntu'
GROUP BY
FileChanges.FileName
ORDER BY
ChangeCount DESC
Diff Code Blocks
```diff
diff --git a/README.md b/README.md
index 92555a2..b49c0bb 100644
--- a/README.md
+++ b/README.md
@@ -377,8 +377,12 @@ As a general note, avoiding abbreviations provides better readability.
* follow the [Policy Style Guide](manuals/policy-style.markdown)
in examples and code snippets
-* always run it through Pygments plus the appropriate lexer (only cf3
- supported for now)
+* always run it through Pygments plus the appropriate lexer
+
+Most important are the `cf3` lexer, as well as `bash`, `console`,
+`diff`, `shell-session` and `postgresql`. But Jekyll supports
+[many more lexers](http://pygments.org/docs/lexers/)
+
* avoid custom color schemes and hand-coded HTML
* document the example after the example code
```
diff --git a/README.md b/README.md
index 92555a2..b49c0bb 100644
--- a/README.md
+++ b/README.md
@@ -377,8 +377,12 @@ As a general note, avoiding abbreviations provides better readability.
* follow the [Policy Style Guide](manuals/policy-style.markdown)
in examples and code snippets
-* always run it through Pygments plus the appropriate lexer (only cf3
- supported for now)
+* always run it through Pygments plus the appropriate lexer
+
+Most important are the `cf3` lexer, as well as `bash`, `console`,
+`diff`, `shell-session` and `postgresql`. But Jekyll supports
+[many more lexers](http://pygments.org/docs/lexers/)
+
* avoid custom color schemes and hand-coded HTML
* document the example after the example code
JSON Code Blocks
YAML Code Blocks
---
classes:
services_autorun:
- "any"
---
classes:
services_autorun:
- "any"
Code Blocks and Lists
If you want to include a code block within a list, put two tabs (8 spaces) in front of the entire block (4 to make the paragraph part of the list item, and 4 for it a code block):
* List item with code
<code goes here>
List item with code
<code goes here>
You can also use backticks (and get syntax highlighting) - just make sure the backticks are indented once:
1. First
```cf3
# CFEngine block
bundle agent example()
{
}
```
2. Second
3. Third
First
# CFEngine block bundle agent example() { }
Second
Third
Headers
Horizontal bar
***
# Level 1
Level 1
## Level 2
Level 2
### Level 3
Level 3
#### Level 4
Level 4
##### Level 5
Level 5
###### Level 6
Level 6
Including External Files
Sometimes it's nice to include an external file
# Changelog Notable changes to the framework should be documented here ## [Unreleased][unreleased] ### Added - External watchdog policy to ensure that cf-execd is running so that policy will be run on schedule. - This policy configures /etc/cron.d/cfengine_watchdog if /etc/cron.d is present to check for cf-execd once a minute and launch it if it is not running. - The policy can be enabled by defining the class cfe_internal_core_watchdog_enabled, or disabled by defining cfe_internal_core_watchdog_disabled. In the event both classes are defined at the same time enabled wins. ### Fixed - Augmenting inputs from the augments_file (Redmine #7420) ## 3.7.0 ### Added - CHANGELOG.md - Support for user specified overring of framework defaults without modifying policy supplied by the framework itself (see example_def.json) - Support for def.json class augmentation in update policy - Run vacuum operation on postgresql every night as a part of maintenance. - Add measure_promise_time action body to lib (3.5, 3.6, 3.7, 3.8) - New negative class guard `cfengine_internal_disable_agent_email` so that agent email can be easily disabled by augmenting def.json ### Changed - Relocate def.cf to controls/VER/ - Relocate update_def to controls/VER - Relocate all controls to controls/VER - Only load cf_hub and reports.cf on CFEngine Enterprise installs - Relocate acls related to report collection from bundle server access_rules to controls/VER/reports.cf into bundle server report_access_rules - Re-organize cfe_internal splitting core from enterprise specific policies and loading the appropriate inputs only when necessary - Moved update directory into cfe_internal as it is not generally intended to be modified - services/autorun.cf moved to lib/VER/ as it is not generally intended to be modified - To improve predictibility autorun bundles are activated in lexicographical order - Relocate services/file_change.cf to cfe_internal/enterprise. This policy is most useful for a good OOTB experience with CFEngine Enterprise Mission Portal. - Relocate service_catalogue from promsies.cf to services/main.cf. It is intended to be a user entry. This name change correlates with the main bundle being activated by default if there is no bundlesequence specified. - Reduce benchmarks sample history to 1 day. - Update policy no longer generates a keypair if one is not found. (Redmine: #7167) - Relocate cfe_internal_postgresql_maintenance bundle to lib/VER/ - Set postgresql_monitoring_maintenance only for versions 3.6.0 and 3.6.1 - Move hub specific bundles from lib/VER/cfe_internal.cf into lib/VER/cfe_internal_hub.cf and load them only if policy_server policy if set. - Re-organize lib/VER/stdlib.cf from lists into classic array for use with getvalues - inform_mode classes changed to DEBUG|DEBUG_$(this.bundle):: (Redmine: #7191) - Enabled limit_robot_agents in order to work around multiple cf-execd processes after upgrade. (Redmine #7185) ### Deprecated ### Removed - Diff reporting on /etc/shadow (Enterprise) - Update policy from promise.cf inputs. There is no reason to include the update policy into promsies.cf, update.cf is the entry for the update policy - _not_repaired outcome from classes_generic and scoped_classes generic (Redmine: # 7022) ### Fixed - standard_services now restarts the service if it was not already running when using service_policy => restart with chkconfig (Redmine #7258) - Fix process_result logic to match the purpose of body process_select days_older_than (Redmine #3009) ### Security
Comments inside documentation
Sometimes it's nice to be able to put an internal comment into the documentation that will not be rendered.
You can use the comment and endcomment tags in markdown files.
For example:
{% comment %} TODO: We should try to improve this at some point.{% endcomment %}
Would render like this:
Sandbox
symlink example
body link_from ln_s(x)
{
link_type => "symlink";
source => "$(x)";
when_no_source => "force";
}
Variables
Referencing a version of CFEngine? Consider if that appearance should be updated with each new version.
Variables that are defined in the front matter (thats the content between the three dashes at the top) or in _config.yaml in the documentation-generator repository can be used directly within markdown.
For example this is the '3.9' version of the documentation. That variable comes from _config.yaml.
Since liquid variables look a lot like mustache variables any time you want to show the actual variables will need to be inside of raw tags.
site.CFE_manuals_version {{ site.CFE_manuals_version }}