Click here to Skip to main content
13,795,074 members
Click here to Skip to main content
Add your own
alternative version

Tagged as

Stats

33.2K views
26 bookmarked
Posted 26 Feb 2015
Licenced CPOL

Article Formatting tips for CodeProject

, 26 Feb 2015
Rate this:
Please Sign up or sign in to vote.
Some tips and tricks to help you format your articles and tips simply and consistently.

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

  1. 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.
     
  2. 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.
     
  3. 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

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

       
    •  DIV elements you can use the following:
      <div class="callout">This is a callout</div>
      This is a callout
      <div class="sidebar-left">This is a left-sidebar</div>
      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
       
      <div class="sidebar-right">This is a right-sidebar</div>
      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
      <div class="sidebar">This is a sidebar (no float or outer text wrapping)</div>
      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:
      <a class="external" href="http://www.google.com">Remember to search first, then ask.</a>

      Remember to search first, then ask

  2. 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".
     
  3. 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.
     
  4. 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..
    <div class="code-samples">
    <pre lang="C#">
    ...
    // some C# code
    ...
    </pre>
    <pre lang="VB.NET">
    ...
    ' some VB code
    ...
    </pre>
    </div>

    This will result in

    ...
    // some C# code
    ...
    ...
    ' 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
    <pre lang="aspnet" linecount="true">
    or
    <pre lang="vb" linecount="true" countstart="10" countincrement="10"> 

    This will result in

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

    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})

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

Chris Maunder
Founder CodeProject
Canada Canada
Chris is the Co-founder, Administrator, Architect, Chief Editor and Shameless Hack who wrote and runs The Code Project. He's been programming since 1988 while pretending to be, in various guises, an astrophysicist, mathematician, physicist, hydrologist, geomorphologist, defence intelligence researcher and then, when all that got a bit rough on the nerves, a web developer. He is a Microsoft Visual C++ MVP both globally and for Canada locally.

His programming experience includes C/C++, C#, SQL, MFC, ASP, ASP.NET, and far, far too much FORTRAN. He has worked on PocketPCs, AIX mainframes, Sun workstations, and a CRAY YMP C90 behemoth but finds notebooks take up less desk space.

He dodges, he weaves, and he never gets enough sleep. He is kind to small animals.

Chris was born and bred in Australia but splits his time between Toronto and Melbourne, depending on the weather. For relaxation he is into road cycling, snowboarding, rock climbing, and storm chasing.

You may also be interested in...

Comments and Discussions

 
QuestionWhat would be the best way to add an anchor to "pre" element? Pin
Sergey Alexandrovich Kryukov30-Jun-17 12:12
mvpSergey Alexandrovich Kryukov30-Jun-17 12:12 
AnswerRe: What would be the best way to add an anchor to "pre" element? Pin
Thomas D [ProgramFOX]3-Aug-17 22:44
mvpThomas D [ProgramFOX]3-Aug-17 22:44 
GeneralRe: What would be the best way to add an anchor to "pre" element? Pin
Sergey Alexandrovich Kryukov4-Aug-17 7:09
mvpSergey Alexandrovich Kryukov4-Aug-17 7:09 
GeneralRe: What would be the best way to add an anchor to "pre" element? Pin
Thomas D [ProgramFOX]4-Aug-17 7:19
mvpThomas D [ProgramFOX]4-Aug-17 7:19 
AnswerRe: What would be the best way to add an anchor to "pre" element? Pin
Sergey Alexandrovich Kryukov4-Aug-17 8:12
mvpSergey Alexandrovich Kryukov4-Aug-17 8:12 
Praise:) Pin
Member 1124779614-Jun-17 10:11
memberMember 1124779614-Jun-17 10:11 
QuestionHi. I'm still unable to type formulas in my articles using LaTeX script Pin
Arthur V. Ratz20-Jan-17 20:58
mvpArthur V. Ratz20-Jan-17 20:58 
QuestionHow I can highlight text? Pin
Martin Radu20-Dec-16 8:40
memberMartin Radu20-Dec-16 8:40 
AnswerRe: How I can highlight text? Pin
Sergey Alexandrovich Kryukov30-Jun-17 12:16
mvpSergey Alexandrovich Kryukov30-Jun-17 12:16 
QuestionAm I patently stupid or something. Pin
rerhart5857-Dec-16 2:26
memberrerhart5857-Dec-16 2:26 
GeneralMy vote of 5 Pin
Suvendu Shekhar Giri25-Jun-16 21:20
professionalSuvendu Shekhar Giri25-Jun-16 21:20 
QuestionIssues with Images Pin
Jitendra_Jain0423-Apr-15 5:30
memberJitendra_Jain0423-Apr-15 5:30 
GeneralMy vote of 5 Pin
Afzaal Ahmad Zeeshan2-Mar-15 10:21
mvpAfzaal Ahmad Zeeshan2-Mar-15 10:21 
QuestionGreat Tip Article Pin
Ryan S White1-Mar-15 19:26
professionalRyan S White1-Mar-15 19:26 
GeneralMy vote of 5 Pin
DrABELL26-Feb-15 18:07
professionalDrABELL26-Feb-15 18:07 
GeneralRe: My vote of 5 Pin
thewazz2-Mar-15 8:17
professionalthewazz2-Mar-15 8:17 
GeneralRe: My vote of 5 Pin
thewazz2-Mar-15 8:20
professionalthewazz2-Mar-15 8:20 
GeneralRe: My vote of 5 Pin
Chris Maunder2-Mar-15 10:59
adminChris Maunder2-Mar-15 10:59 
GeneralRe: My vote of 5 Pin
DrABELL2-Mar-15 11:26
professionalDrABELL2-Mar-15 11:26 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

Permalink | Advertise | Privacy | Cookies | Terms of Use | Mobile
Web03 | 2.8.181207.3 | Last Updated 26 Feb 2015
Article Copyright 2015 by Chris Maunder
Everything else Copyright © CodeProject, 1999-2018
Layout: fixed | fluid