publish/documentation/latest/markdown-style-guide/index.html - mesos-site - Git at Google

 <!DOCTYPE html>
 <html>
   <head>
     <meta charset="utf-8">
     <title>Apache Mesos - Markdown Style Guide</title>
     <meta name="viewport" content="width=device-width, initial-scale=1.0">

     <meta property="og:locale" content="en_US"/>
     <meta property="og:type" content="website"/>
     <meta property="og:title" content="Apache Mesos"/>
     <meta property="og:site_name" content="Apache Mesos"/>
     <meta property="og:url" content="http://mesos.apache.org/"/>
     <meta property="og:image" content="http://mesos.apache.org/assets/img/mesos_logo_fb_preview.png"/>
     <meta property="og:description"
           content="Apache Mesos abstracts resources away from machines,
                    enabling fault-tolerant and elastic distributed systems
                    to easily be built and run effectively."/>

     <meta name="twitter:card" content="summary"/>
     <meta name="twitter:site" content="@ApacheMesos"/>
     <meta name="twitter:title" content="Apache Mesos"/>
     <meta name="twitter:image" content="http://mesos.apache.org/assets/img/mesos_logo_fb_preview.png"/>
     <meta name="twitter:description"
           content="Apache Mesos abstracts resources away from machines,
                    enabling fault-tolerant and elastic distributed systems
                    to easily be built and run effectively."/>

     <link href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css" rel="stylesheet">
     <link rel="alternate" type="application/atom+xml" title="Apache Mesos Blog" href="/blog/feed.xml">
     <link href="../../../assets/css/main.css" media="screen" rel="stylesheet" type="text/css" />


     <!-- Google Analytics Magic -->
     <script type="text/javascript">
     var _gaq = _gaq || [];
     _gaq.push(['_setAccount', 'UA-20226872-1']);
     _gaq.push(['_setDomainName', 'apache.org']);
     _gaq.push(['_trackPageview']);

     (function() {
       var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
       ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
       var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
     })();
     </script>

   </head>
   <body>
     <!-- magical breadcrumbs -->
     <div class="topnav">
       <div class="container">
         <ul class="breadcrumb">
           <li>
             <div class="dropdown">
               <a data-toggle="dropdown" href="#">Apache Software Foundation <span class="caret"></span></a>
               <ul class="dropdown-menu" role="menu" aria-labelledby="dLabel">
                 <li><a href="http://www.apache.org">Apache Homepage</a></li>
                 <li><a href="http://www.apache.org/licenses/">License</a></li>
                 <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
                 <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
                 <li><a href="http://www.apache.org/security/">Security</a></li>
               </ul>
             </div>
           </li>

           <li><a href="http://mesos.apache.org">Apache Mesos</a></li>


           <li><a href="/documentation
 /">Documentation
 </a></li>


         </ul><!-- /.breadcrumb -->
       </div><!-- /.container -->
     </div><!-- /.topnav -->

     <!-- navbar excitement -->
 <div class="navbar navbar-default navbar-static-top" role="navigation">
   <div class="container">
     <div class="navbar-header">
       <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#mesos-menu" aria-expanded="false">
       <span class="sr-only">Toggle navigation</span>
       <span class="icon-bar"></span>
       <span class="icon-bar"></span>
       <span class="icon-bar"></span>
       </button>
       <a class="navbar-brand" href="/"><img src="/assets/img/mesos_logo.png" alt="Apache Mesos logo"/></a>
     </div><!-- /.navbar-header -->

     <div class="navbar-collapse collapse" id="mesos-menu">
       <ul class="nav navbar-nav navbar-right">
         <li><a href="/gettingstarted/">Getting Started</a></li>
         <li><a href="/blog/">Blog</a></li>
         <li><a href="/documentation/latest/">Documentation</a></li>
         <li><a href="/downloads/">Downloads</a></li>
         <li><a href="/community/">Community</a></li>
       </ul>
     </div><!-- /#mesos-menu -->
   </div><!-- /.container -->
 </div><!-- /.navbar -->

 <div class="content">
   <div class="container">
     <div class="row-fluid">
   <div class="col-md-4">
     <h4>If you're new to Mesos</h4>
     <p>See the <a href="/gettingstarted/">getting started</a> page for more
        information about downloading, building, and deploying Mesos.</p>

     <h4>If you'd like to get involved or you're looking for support</h4>
     <p>See our <a href="/community/">community</a> page for more details.</p>
   </div>
   <div class="col-md-8">
     <h1>Mesos Markdown Style Guide</h1>

 <p>This guide introduces a consistent documentation style to be used across the entire non-code documentation.
 User guides and non-code technical documentation are stored in markdown files in the <code>docs/</code> folder. These files get rendered for the <a href="http://mesos.apache.org/documentation/latest/">online documentation</a>.</p>

 <p><strong>NOTE:</strong> As of right now this is work in progress and the existing documentation might not yet comply to this style.</p>

 <h2>What to Document?</h2>

 <p>Any new substantial feature should be documented in its own markdown file.
 If the link between source code and documentation is not obvious, consider inserting a short code comment stating that there is non-code documentation that needs to be kept in sync and indicating where it is located.</p>

 <h2>Keep Documentation and Style Guides in Sync with Code.</h2>

 <p>When changing code consider whether you need to update the documentation.
 This is especially relevant when introducing new or updating existing command line flags.
 These should be reflected in <code>configuration.md</code>!</p>

 <h2>Section Headings</h2>

 <p>Use <a href="https://en.wikipedia.org/wiki/Capitalization#Title_case">title case</a> for
 section headings, preferably the
 <a href="http://blog.apastyle.org/apastyle/headings/">APA style</a> variant:</p>

 <ul>
 <li>Capitalize the first word of any heading, including title, subtitle,
 subheading.</li>
 <li>Capitalize all &ldquo;major&rdquo; words (nouns, verbs, adjectives, adverbs, and pronouns)
 in any heading, including the second part of hyphenated major words (e.g.,
 Self-Report not Self-report).</li>
 <li>Capitalize all words of five letters or more.</li>
 </ul>


 <p>Effectively, only &ldquo;minor&rdquo; words of four letters or fewer, namely, conjunctions
 (words like <strong>and</strong>, <strong>or</strong>, <strong>nor</strong>, and <strong>but</strong>), articles (the words <strong>a</strong>,
 <strong>an</strong>, and <strong>the</strong>), and prepositions (words like <strong>as</strong>, <strong>at</strong>, <strong>by</strong>,
 <strong>for</strong>, <strong>from</strong>, <strong>in</strong>, <strong>of</strong>, <strong>on</strong>, <strong>per</strong>, <strong>to</strong>, <strong>with</strong>), are
 lowercased in any heading, as long as they aren&rsquo;t the first word.</p>

 <h2>Code Examples</h2>

 <p>Code examples should be specified as follows:</p>

 <pre><code>~~~{.cpp}
 int main(int argc, char** argv)
 {
   ....
 }
 ~~~
 </code></pre>

 <p><strong>NOTE:</strong> Because of shortcomings of Doxygen&rsquo;s markdown parser we currently use indentation for wrapping all non C++ code blocks.</p>

 <h2>Notes/Emphasis</h2>

 <p>Notes are used to highlight important parts of the text and should be specified as follows.</p>

 <pre><code class="{.txt}">**NOTE:**  Short note.
 Continued longer note.
 </code></pre>

 <p>We use single backticks to highlight individual words in a sentence such as certain identifiers:</p>

 <pre><code class="{.txt}">Use the default `HierarchicalDRF` allocator....
 </code></pre>

 <h2>Commands</h2>

 <p>We use single backticks to highlight sample commands as follows:</p>

 <pre><code class="{.txt}">`mesos-master --help`
 </code></pre>

 <h2>Files/Paths</h2>

 <p>Files and path references should be specified as follows:</p>

 <pre><code class="{.txt}">Remember you can also use the `file:///path/to/file` or `/path/to/file`
 </code></pre>

 <h2>Tables</h2>

 <p>In order to avoid problems with markdown formatting we should specify tables in html directly:</p>

 <pre><code>&lt;table class="table table-striped"&gt;
   &lt;thead&gt;
     &lt;tr&gt;
       &lt;th width="30%"&gt;
         Flag
       &lt;/th&gt;
       &lt;th&gt;
         Explanation
       &lt;/th&gt;
   &lt;/thead&gt;
   &lt;tr&gt;
     &lt;td&gt;
       --ip=VALUE
     &lt;/td&gt;
     &lt;td&gt;
       IP address to listen on
     &lt;/td&gt;
   &lt;/tr&gt;
   &lt;tr&gt;
     &lt;td&gt;
       --[no-]help
     &lt;/td&gt;
     &lt;td&gt;
       Prints this help message (default: false)
     &lt;/td&gt;
   &lt;/tr&gt;
 &lt;/table&gt;
 </code></pre>

 <h2>Indentation and Whitespace</h2>

 <p>We use no extra indentation in markdown files.
 We have one new line after section headings and two blank lines
 in between sections.</p>

 <pre><code class="{.txt}">... end of previous section.


 ## New Section

 Beginning of new section ....
 </code></pre>

   </div>
 </div>

   </div><!-- /.container -->
 </div><!-- /.content -->

 <hr>


     <!-- footer -->
     <div class="footer">
       <div class="container">
         <div class="col-md-4 social-blk">
           <span class="social">
             <a href="https://twitter.com/ApacheMesos"
               class="twitter-follow-button"
               data-show-count="false" data-size="large">Follow @ApacheMesos</a>
             <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script>
             <a href="https://twitter.com/intent/tweet?button_hashtag=mesos"
               class="twitter-hashtag-button"
               data-size="large"
               data-related="ApacheMesos">Tweet #mesos</a>
             <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script>
           </span>
         </div>

         <div class="col-md-8 trademark">
           <p>&copy; 2012-2017 <a href="http://apache.org">The Apache Software Foundation</a>.
             Apache Mesos, the Apache feather logo, and the Apache Mesos project logo are trademarks of The Apache Software Foundation.
           <p>
         </div>
       </div><!-- /.container -->
     </div><!-- /.footer -->

     <!-- JS -->
     <script src="//code.jquery.com/jquery-1.11.0.min.js" type="text/javascript"></script>
     <script src="//netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js" type="text/javascript"></script>
   </body>
 </html>
	<!DOCTYPE html>
	<html>
	<head>
	<meta charset="utf-8">
	<title>Apache Mesos - Markdown Style Guide</title>
	<meta name="viewport" content="width=device-width, initial-scale=1.0">

	<meta property="og:locale" content="en_US"/>
	<meta property="og:type" content="website"/>
	<meta property="og:title" content="Apache Mesos"/>
	<meta property="og:site_name" content="Apache Mesos"/>
	<meta property="og:url" content="http://mesos.apache.org/"/>
	<meta property="og:image" content="http://mesos.apache.org/assets/img/mesos_logo_fb_preview.png"/>
	<meta property="og:description"
	content="Apache Mesos abstracts resources away from machines,
	enabling fault-tolerant and elastic distributed systems
	to easily be built and run effectively."/>

	<meta name="twitter:card" content="summary"/>
	<meta name="twitter:site" content="@ApacheMesos"/>
	<meta name="twitter:title" content="Apache Mesos"/>
	<meta name="twitter:image" content="http://mesos.apache.org/assets/img/mesos_logo_fb_preview.png"/>
	<meta name="twitter:description"
	content="Apache Mesos abstracts resources away from machines,
	enabling fault-tolerant and elastic distributed systems
	to easily be built and run effectively."/>

	<link href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css" rel="stylesheet">
	<link rel="alternate" type="application/atom+xml" title="Apache Mesos Blog" href="/blog/feed.xml">
	<link href="../../../assets/css/main.css" media="screen" rel="stylesheet" type="text/css" />



	<!-- Google Analytics Magic -->
	<script type="text/javascript">
	var _gaq = _gaq \|\| [];
	_gaq.push(['_setAccount', 'UA-20226872-1']);
	_gaq.push(['_setDomainName', 'apache.org']);
	_gaq.push(['_trackPageview']);

	(function() {
	var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
	ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
	var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
	})();
	</script>

	</head>
	<body>
	<!-- magical breadcrumbs -->
	<div class="topnav">
	<div class="container">
	<ul class="breadcrumb">
	<li>
	<div class="dropdown">
	<a data-toggle="dropdown" href="#">Apache Software Foundation <span class="caret"></span></a>
	<ul class="dropdown-menu" role="menu" aria-labelledby="dLabel">
	<li><a href="http://www.apache.org">Apache Homepage</a></li>
	<li><a href="http://www.apache.org/licenses/">License</a></li>
	<li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
	<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
	<li><a href="http://www.apache.org/security/">Security</a></li>
	</ul>
	</div>
	</li>

	<li><a href="http://mesos.apache.org">Apache Mesos</a></li>


	<li><a href="/documentation
	/">Documentation
	</a></li>


	</ul><!-- /.breadcrumb -->
	</div><!-- /.container -->
	</div><!-- /.topnav -->

	<!-- navbar excitement -->
	<div class="navbar navbar-default navbar-static-top" role="navigation">
	<div class="container">
	<div class="navbar-header">
	<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#mesos-menu" aria-expanded="false">
	<span class="sr-only">Toggle navigation</span>
	<span class="icon-bar"></span>
	<span class="icon-bar"></span>
	<span class="icon-bar"></span>
	</button>
	<a class="navbar-brand" href="/"><img src="/assets/img/mesos_logo.png" alt="Apache Mesos logo"/></a>
	</div><!-- /.navbar-header -->

	<div class="navbar-collapse collapse" id="mesos-menu">
	<ul class="nav navbar-nav navbar-right">
	<li><a href="/gettingstarted/">Getting Started</a></li>
	<li><a href="/blog/">Blog</a></li>
	<li><a href="/documentation/latest/">Documentation</a></li>
	<li><a href="/downloads/">Downloads</a></li>
	<li><a href="/community/">Community</a></li>
	</ul>
	</div><!-- /#mesos-menu -->
	</div><!-- /.container -->
	</div><!-- /.navbar -->

	<div class="content">
	<div class="container">
	<div class="row-fluid">
	<div class="col-md-4">
	<h4>If you're new to Mesos</h4>
	<p>See the <a href="/gettingstarted/">getting started</a> page for more
	information about downloading, building, and deploying Mesos.</p>

	<h4>If you'd like to get involved or you're looking for support</h4>
	<p>See our <a href="/community/">community</a> page for more details.</p>
	</div>
	<div class="col-md-8">
	<h1>Mesos Markdown Style Guide</h1>

	<p>This guide introduces a consistent documentation style to be used across the entire non-code documentation.
	User guides and non-code technical documentation are stored in markdown files in the <code>docs/</code> folder. These files get rendered for the <a href="http://mesos.apache.org/documentation/latest/">online documentation</a>.</p>

	<p><strong>NOTE:</strong> As of right now this is work in progress and the existing documentation might not yet comply to this style.</p>

	<h2>What to Document?</h2>

	<p>Any new substantial feature should be documented in its own markdown file.
	If the link between source code and documentation is not obvious, consider inserting a short code comment stating that there is non-code documentation that needs to be kept in sync and indicating where it is located.</p>

	<h2>Keep Documentation and Style Guides in Sync with Code.</h2>

	<p>When changing code consider whether you need to update the documentation.
	This is especially relevant when introducing new or updating existing command line flags.
	These should be reflected in <code>configuration.md</code>!</p>

	<h2>Section Headings</h2>

	<p>Use <a href="https://en.wikipedia.org/wiki/Capitalization#Title_case">title case</a> for
	section headings, preferably the
	<a href="http://blog.apastyle.org/apastyle/headings/">APA style</a> variant:</p>

	<ul>
	<li>Capitalize the first word of any heading, including title, subtitle,
	subheading.</li>
	<li>Capitalize all “major” words (nouns, verbs, adjectives, adverbs, and pronouns)
	in any heading, including the second part of hyphenated major words (e.g.,
	Self-Report not Self-report).</li>
	<li>Capitalize all words of five letters or more.</li>
	</ul>


	<p>Effectively, only “minor” words of four letters or fewer, namely, conjunctions
	(words like <strong>and</strong>, <strong>or</strong>, <strong>nor</strong>, and <strong>but</strong>), articles (the words <strong>a</strong>,
	<strong>an</strong>, and <strong>the</strong>), and prepositions (words like <strong>as</strong>, <strong>at</strong>, <strong>by</strong>,
	<strong>for</strong>, <strong>from</strong>, <strong>in</strong>, <strong>of</strong>, <strong>on</strong>, <strong>per</strong>, <strong>to</strong>, <strong>with</strong>), are
	lowercased in any heading, as long as they aren’t the first word.</p>

	<h2>Code Examples</h2>

	<p>Code examples should be specified as follows:</p>

	<pre><code>~~~{.cpp}
	int main(int argc, char** argv)
	{
	....
	}
	~~~
	</code></pre>

	<p><strong>NOTE:</strong> Because of shortcomings of Doxygen’s markdown parser we currently use indentation for wrapping all non C++ code blocks.</p>

	<h2>Notes/Emphasis</h2>

	<p>Notes are used to highlight important parts of the text and should be specified as follows.</p>

	<pre><code class="{.txt}">NOTE: Short note.
	Continued longer note.
	</code></pre>

	<p>We use single backticks to highlight individual words in a sentence such as certain identifiers:</p>

	<pre><code class="{.txt}">Use the default `HierarchicalDRF` allocator....
	</code></pre>

	<h2>Commands</h2>

	<p>We use single backticks to highlight sample commands as follows:</p>

	<pre><code class="{.txt}">`mesos-master --help`
	</code></pre>

	<h2>Files/Paths</h2>

	<p>Files and path references should be specified as follows:</p>

	<pre><code class="{.txt}">Remember you can also use the `file:///path/to/file` or `/path/to/file`
	</code></pre>

	<h2>Tables</h2>

	<p>In order to avoid problems with markdown formatting we should specify tables in html directly:</p>

	<pre><code><table class="table table-striped">
	<thead>
	<tr>
	<th width="30%">
	Flag
	</th>
	<th>
	Explanation
	</th>
	</thead>
	<tr>
	<td>
	--ip=VALUE
	</td>
	<td>
	IP address to listen on
	</td>
	</tr>
	<tr>
	<td>
	--[no-]help
	</td>
	<td>
	Prints this help message (default: false)
	</td>
	</tr>
	</table>
	</code></pre>

	<h2>Indentation and Whitespace</h2>

	<p>We use no extra indentation in markdown files.
	We have one new line after section headings and two blank lines
	in between sections.</p>

	<pre><code class="{.txt}">... end of previous section.


	## New Section

	Beginning of new section ....
	</code></pre>

	</div>
	</div>

	</div><!-- /.container -->
	</div><!-- /.content -->

	<hr>



	<!-- footer -->
	<div class="footer">
	<div class="container">
	<div class="col-md-4 social-blk">
	<span class="social">
	<a href="https://twitter.com/ApacheMesos"
	class="twitter-follow-button"
	data-show-count="false" data-size="large">Follow @ApacheMesos</a>
	<script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script>
	<a href="https://twitter.com/intent/tweet?button_hashtag=mesos"
	class="twitter-hashtag-button"
	data-size="large"
	data-related="ApacheMesos">Tweet #mesos</a>
	<script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script>
	</span>
	</div>

	<div class="col-md-8 trademark">
	<p>© 2012-2017 <a href="http://apache.org">The Apache Software Foundation</a>.
	Apache Mesos, the Apache feather logo, and the Apache Mesos project logo are trademarks of The Apache Software Foundation.
	<p>
	</div>
	</div><!-- /.container -->
	</div><!-- /.footer -->

	<!-- JS -->
	<script src="//code.jquery.com/jquery-1.11.0.min.js" type="text/javascript"></script>
	<script src="//netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js" type="text/javascript"></script>
	</body>
	</html>