Edit online

Tables are widely used in technical documentation. This section contains information about the CSS rules that are used to style them and how to fix some problems.

Edit online

There is a combination of CSS files that address tables:
  • [PLUGIN_DIR]/css/core/-table-html-cals.css
  • [PLUGIN_DIR]/css/print/p-tables.css

Edit online

Some of the tables can have a large number of columns. In this case, the table may bleed out of the page. One solution is to use landscape pages for these tables.

Setting the attribute @orient = 'land' on the table element will force the table on a new landscape page.

Another solution is to use automatic detection of wide tables (5 or more columns):

*[class~="topic/table"] > *[class~="topic/tgroup"][cols='5'],
*[class~="topic/table"] > *[class~="topic/tgroup"][cols='6'],
*[class~="topic/table"] > *[class~="topic/tgroup"][cols='7'],
*[class~="topic/table"] > *[class~="topic/tgroup"][cols='8'] {
    page: landscape-page;
    max-width: 100%;
    page-break-before: avoid;
}    
Note: The landscape-page page layout is defined in the [PLUGIN_DIR]css/print/p-pages-and-headers.css.

If you want to rotate the entire topic that contains the big table, use:

*[class~="topic/table"] > *[class~="topic/tgroup"][cols='5'],
*[class~="topic/table"] > *[class~="topic/tgroup"][cols='6'],
*[class~="topic/table"] > *[class~="topic/tgroup"][cols='7'],
*[class~="topic/table"] > *[class~="topic/tgroup"][cols='8'] {
    max-width: 100%;
    table-layout:auto;
}

*[class~="topic/topic"]:has(*:not([class~="topic/topic"]) > *[class~="topic/table"] > *[class~="topic/tgroup"][cols='5']),
*[class~="topic/topic"]:has(*:not([class~="topic/topic"]) > *[class~="topic/table"] > *[class~="topic/tgroup"][cols='6']),
*[class~="topic/topic"]:has(*:not([class~="topic/topic"]) > *[class~="topic/table"] > *[class~="topic/tgroup"][cols='7']),
*[class~="topic/topic"]:has(*:not([class~="topic/topic"]) > *[class~="topic/table"] > *[class~="topic/tgroup"][cols='8']),
*[class~="topic/topic"]:has(*:not([class~="topic/topic"]) > *:not([class~="topic/topic"]) > *[class~="topic/table"] > *[class~="topic/tgroup"][cols='5']),
*[class~="topic/topic"]:has(*:not([class~="topic/topic"]) > *:not([class~="topic/topic"]) > *[class~="topic/table"] > *[class~="topic/tgroup"][cols='6']),
*[class~="topic/topic"]:has(*:not([class~="topic/topic"]) > *:not([class~="topic/topic"]) > *[class~="topic/table"] > *[class~="topic/tgroup"][cols='7']),
*[class~="topic/topic"]:has(*:not([class~="topic/topic"]) > *:not([class~="topic/topic"]) > *[class~="topic/table"] > *[class~="topic/tgroup"][cols='8']),
*[class~="topic/topic"]:has(*:not([class~="topic/topic"]) > *:not([class~="topic/topic"]) > *:not([class~="topic/topic"]) > *[class~="topic/table"] > *[class~="topic/tgroup"][cols='5']),
*[class~="topic/topic"]:has(*:not([class~="topic/topic"]) > *:not([class~="topic/topic"]) > *:not([class~="topic/topic"]) > *[class~="topic/table"] > *[class~="topic/tgroup"][cols='6']),
*[class~="topic/topic"]:has(*:not([class~="topic/topic"]) > *:not([class~="topic/topic"]) > *:not([class~="topic/topic"]) > *[class~="topic/table"] > *[class~="topic/tgroup"][cols='7']),
*[class~="topic/topic"]:has(*:not([class~="topic/topic"]) > *:not([class~="topic/topic"]) > *:not([class~="topic/topic"]) > *[class~="topic/table"] > *[class~="topic/tgroup"][cols='8']){
      page: landscape-page;
}

Edit online

Slim tables or tables that have many columns make the text from the cells to be confined to a small horizontal space. Long words would bleed outside the cell boundaries. To fix this, you should enable hyphenation in your tables, thus making the words spread on multiple lines. In your customization CSS, add:

*[class~="topic/table"] {
    hyphens: auto;
}

Edit online

The DITA specification indicates that tables should have a fixed layout. However, you can get a more optimal arrangement of the cells using the automatic layout. In your customization CSS, add:

*[class~="topic/tgroup"] {
    table-layout:auto !important;
}
If you want to control which table you want this layout, you can set the @outputclass attribute on the <table> element:
<table outputclass='auto_tbl'> ... </table>
Then, in the CSS, use a rule that matches the @outputclass:
*[class~="topic/table"][outputclass='auto_tbl'] > *[class~="topic/tgroup"] {
    table-layout:auto !important;
}
Important: Make sure the tables have no column width specified.

Edit online

There are cases where you want to style the first column as a kind of table header, with vertical text.

There is an important thing to remember: you can rotate an element from a table cell, but not the cell itself. So, your DITA table cell should contain a <div> or a <p> element that will be rotated. The cell has to be marked somehow so that it can be matched from the CSS. One way is to set an @outputclass attribute on it, another will be to mark the table and then match the first entries from it.

  <row>
      ...
      <entry outputclass="rotated">
            <p>Rotated</p>
      </entry>
      ...
 </row>

In your customization CSS, use the following rule that matches the child of the entry:

*[outputclass ~= "rotated"] > * {
  display: block;
  transform: rotate(-90deg) !important;
  text-align: left !important;

  padding:0; 
  margin:0;
 
  white-space: nowrap;

  width:150px; 
  height:80px; 
}

The padding and margins are set to zero to clear any space that may come from other rules. The width is required - it will become the height of the cell. If this is not specified, the vertical rotated text will bleed out of the cell. The height is optional.

Edit online

To add horizontal lines that separate the options within a <choicetable>, you can use borders set on each of the rows. The following CSS styles the top header and the first column with some background colors. In a choice table, the first column represents the choice labels.

*[class~="task/choptionhd"],
*[class~="task/choptionhd"],
*[class~="task/chdeschd"],
*[class~="task/choption"] {
	background-color: #EEEEEE;	
	text-align: left;
}

*[class~="task/choicetable"] {
	border: 2pt solid #EEEEEE;
}

*[class~="task/choicetable"] *[class~="task/chrow"],
*[class~="task/choicetable"] *[class~="task/chhead"]{
	border-bottom: 2pt solid #EEEEEE;
} 

*[class~="task/choicetable"] *[class~="topic/stentry"] {
	border-bottom: none;
	border-right: none;
}
Note: Using the frame attribute on the choice table will make these selectors apply partially. Please make sure you are designing your customization CSS taking into account all possible values for the frame attribute.