Article Formatting tips for CodeProject

Introduction

When posting an article on CodeProject we want you to focus on your article's content, not on fancy HTML and CSS tricks. The simpler and cleaner the layout, the easier it is for your readers to consume your work.

With this in mind we've put together some simple rules, guidelines and tricks to help make your life a little easier.

The Motivation

We want the experience of reading an article on CodeProject to be a consistent one. From article to article the layout, styles and formatting should be reasonably uniform in order to make it easy to read.

We also need the freedom to update our stylesheets occasionally, and so sticking to a few simple rules and guidelines allows your articles to maintain current styling without breaking or looking...odd.

The Rules

0. Stick to HTML conventions and use HTML tags as they were meant to be used.
   
   If you use BLOCKQUOTE to indent text then you're assuming the BLOCKQUOTE tag actually indents text on all browsers, and you're also assuming we haven't used CSS to add quote marks or other shenanigans to the output. Use a styled DIV if you wish to indent,
   
   Similarly, use P tags to denote paragraphs. Please don't use BR tags to break paragraphs.
    
1. Use simple HTML only.
   
   By this we mean: stick to the simplest, cleanest HTML possible. Use B or STRONG to make text bold, use CODE tags to outline inline code, and PRE to wrap codeblocks. Don't wrap everything in SPAN blocks with crazy styles: our online editor (and our human editors) will most likely strip it all out.
    
2. No active content such as Javascript or Flash
   
   You won't have permission to add this to your articles anyway. It's a security risk (and potentially annoying to readers). However: if you have a compelling reason you want to have live Javascript in your articles then contact us and we can make exceptions. 

The Guidelines

0. Where possible stick to using our predefined classes when styling HTML elements instead of using inlined styles.
   • SPAN elements can use the filename, command, error, success, and failure classes. e.g.
     HTML

     <span class="command">Save File</span>

   • TABLE elements use the simple, themed, grid, feature and spaced classes. Take note of the use of THEAD elements.
     HTML

     <table class="simple" cellspacing="0" cellpadding="0">
     <thead>
     <tr><td>Col 1</td><td>Col 2</td><td>Col 3</td></tr>
     </thead>
     <tbody><tr><td>1</td><td>2</td><td>3</td></tr>
     <tr><td>A</td><td>B</td><td>C</td></tr>
     </tbody></table>

     Result:

     Col 1	Col 2	Col 3
     1	2	3
     A	B	C

     HTML

     <table class="themed" cellspacing="0" cellpadding="0">
     <thead>
     <tr><td>Col 1</td><td>Col 2</td><td>Col 3</td></tr>
     </thead>
     <tbody><tr><td>1</td><td>2</td><td>3</td></tr>
     <tr><td>A</td><td>B</td><td>C</td></tr>
     </tbody></table>

     Result:

     Col 1	Col 2	Col 3
     1	2	3
     A	B	C

     HTML

     <table class="feature" cellspacing="0" cellpadding="0">
     <thead>
     <tr><td>Col 1</td><td>Col 2</td><td>Col 3</td></tr>
     </thead>
     <tbody><tr><td>1</td><td>2</td><td>3</td></tr>
     <tr><td>A</td><td>B</td><td>C</td></tr>
     </tbody></table>

     Result:

     Col 1	Col 2	Col 3
     1	2	3
     A	B	C

     HTML

     <table class="grid" cellspacing="0" cellpadding="0">
     <thead>
     <tr><td>Col 1</td><td>Col 2</td><td>Col 3</td></tr>
     </thead>
     <tbody><tr><td>1</td><td>2</td><td>3</td></tr>
     <tr><td>A</td><td>B</td><td>C</td></tr>
     </tbody></table>

     Result:

     Col 1	Col 2	Col 3
     1	2	3
     A	B	C

     
      
   •  DIV elements you can use the following:
     HTML

     <div class="callout">This is a callout</div>

     This is a callout
     HTML

     <div class="sidebar-left">This is a left-sidebar</div>

     This is a left-sidebar
     Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse commodo arcu eget scelerisque ultricies. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Ut erat nisl, faucibus eleifend ultricies sit amet, aliquam vitae velit. Nunc feugiat gravida convallis. Ut quis odio rhoncus, facilisis quam at, aliquet velit. Aliquam nec bibendum nulla, quis sollicitudin felis. Maecenas vitae auctor augue, consequat placerat odio. Mauris ac vulputate nisi. Morbi quis enim aliquam, iaculis eros non, vulputate nibh
      
     HTML

     <div class="sidebar-right">This is a right-sidebar</div>

     This is a right-sidebar
     Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse commodo arcu eget scelerisque ultricies. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Ut erat nisl, faucibus eleifend ultricies sit amet, aliquam vitae velit. Nunc feugiat gravida convallis. Ut quis odio rhoncus, facilisis quam at, aliquet velit. Aliquam nec bibendum nulla, quis sollicitudin felis. Maecenas vitae auctor augue, consequat placerat odio. Mauris ac vulputate nisi. Morbi quis enim aliquam, iaculis eros non, vulputate nibh
     HTML

     <div class="sidebar">This is a sidebar (no float or outer text wrapping)</div>

     This is a sidebar (no float or outer text wrapping)
     Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse commodo arcu eget scelerisque ultricies. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Ut erat nisl, faucibus eleifend ultricies sit amet, aliquam vitae velit. Nunc feugiat gravida convallis. Ut quis odio rhoncus, facilisis quam at, aliquet velit. Aliquam nec bibendum nulla, quis sollicitudin felis. Maecenas vitae auctor augue, consequat placerat odio. Mauris ac vulputate nisi. Morbi quis enim aliquam, iaculis eros non, vulputate nibh
      
   • A elements can use the external class to indicate a link to an outside source:

     HTML

     <a class="external" href="http://www.google.com">Remember to search first, then ask.</a>

     Remember to search first, then ask

1. Reduce or eliminate additional spacing or padding around elements
   
   Spacing around elements should be left to our stylesheets to manage. There are exceptions, though such as when you want to control spacing around floating elements. 
   
   To eliminate spacing use class="tight" on elements, and to provide standard spacing use class="spaced".
    
2. Ensure elements are less than 700px wide.
   
   Otherwise elements in your article will either not fit on all screens or will have scrollbars added to them.
    
3. Keep codeblocks as small as possible
   
   No one needs to wade through 1,000 lines of inlined code. Edit out the bits that aren't directly relevant to the explanation. The code will be available in your code download, so no need to repeat yourself.

The Tips and Tricks

• Multiple language versions of the same code
  
  When including code samples within the article text you can provide the same code sample in multiple languages and have them displayed as a neat set of tabs, one tab per language. To do this, post your code samples one after the other, then wrap all the in a DIV with class "code-samples". e.g..
  ASP.NET

  <div class="code-samples">
  <pre lang="C#">
  ...
  // some C# code
  ...
  </pre>
  <pre lang="VB.NET">
  ...
  ' some VB code
  ...
  </pre>
  </div>

  This will result in

  C#

  ...
  // some C# code
  ...

  VB.NET

  ...
  ' some VB code
  ...

  
   
• Adding line counts to code blocks
  
  When including code samples you can have line numbers automatically included be adding linecount="on" to the PRE tag. If you want to start the numbering at a specific line, use countstart="<start>", and to set the line count increment use countincrement="<increment>". eg
  ASP.NET

  <pre lang="aspnet" linecount="true">

  or
  ASP.NET

  <pre lang="vb" linecount="true" countstart="10" countincrement="10"> 

  This will result in

  VB

   10  PRINT "HELLO WORLD"
   20  GOTO 10	
  

  
   
• Using LaTeX in your articles
  
  You can use MathML or TeX in your articles via MathJax. 
  
  Enclose your mathematics within a tag of class "math" and use $...$ to wrap equation blocks and  \(...\) to wrap inline equations.  eg <div class="math">$...$</div>, and wrap an inline equation with <span class="math">\(...\)</span>.
  
  For example:
  HTML

  <div class="math">
  $\begin{aligned}
  \dot{x} & = \sigma(y-x) \\
  \dot{y} & = \rho x - y - xz \\
  \dot{z} & = -\beta z + xy
  \end{aligned}$
  </div> 

  will render as
  $\begin{aligned} \dot{x} & = \sigma(y-x) \\ \dot{y} & = \rho x - y - xz \\ \dot{z} & = -\beta z + xy \end{aligned}$

  and

  HTML

  The solution is <span class="math">\(y = x^2 \hbox{ when x > 2}\)</span>

  will render as

  The solution is \(y = x^2 \hbox{ when x > 2}\)