Search code examples
htmlcsssemanticssemantic-markupresponsive-design

Semantic markup for responsive docblocks

I'm working on some codex like documentation here and I want to write the markup so that it looks like a docblock For example: 

@param   string    lastName     the last name of the person

@param   string    firstName    the first name of the person

@return  string

I'm trying to figure out what are the most semantic elements to use (e.g. pre or dl or table or a combination of div and span) and I also want to make it responsive, so that in small screens via CSS it would look like:

@param   
string    
lastName     
the last name of the person

@param
string
firstName
the first name of the person

@return
string

I've used 2 solutions for this before. The first uses pre with that has some br tags in it which are set to display:none above a certain breakpoint. The other is using a table and a media query like: 

@media all and (max-width:640px) {
    table,thead,tbody,tfoot,th,td,tr{display:block}
    tr+tr{margin-top:1em}
}

I'm open to any other ideas too. What do you think is the most semantic way that is also able to be styled responsively?

Solution

  • After more experimenting, markup like this IMO is the best hybrid of semantic + responsive + cross-browser compatibility. It gives you a lot of CSS flexiblity:

    <dl>
  <dt><b>@param</b> <em>string</em> <strong>first</strong></dt>
  <dd>is the first name</dd>
</dl>
<dl>
  <dt><b>@param</b> <em>string</em> <strong>last</strong></dt>
  <dd>is the last name</dd>
</dl>
<dl>
  <dt><b>@return</b> <em>string</em></dt>
  <dd></dd>
</dl>

    with CSS like:

    dt,dd {display:inline-block;*display:inline;margin:.5em 0}
dd {margin-left:1em}