Customizing the DITA Visual Editing Experience

Instead of copying an entire framework configuration folder (such as DITA or Docbook), modify and distribute it, you can choose to extend that framework and distribute the extension. This way, you will benefit from new functionality added to the base framework by newer Oxygen versions and still use your customizations.

The steps below describe how an extension of the DITA framework that removes certain elements from the content completion list can be constructed and shared:

1. Somewhere on your disk, in a place where you have full write access, create a folder structure like: custom_frameworks/dita-extension.
2. In that folder, create a new CSS stylesheet (for example custom.css) that will contain your custom CSS styles:

   dl{
       display:table !important;
   }
   dlentry{
       display:table-row !important;
   }
   dt, dd {
       display:table-cell !important;
       border: 1px solid black;
       padding: 2px;
   }

3. In the Document Type Association / Locations preferences page, add the path to your custom_frameworks folder in the Additional frameworks directories list. Then click Apply in the Preferences dialog box.
4. In the Document Type Association preferences page, select the DITA document type configuration and use the Extend button to create an extension for it.
5. Give a custom name to the extension (for example DITA - Custom), then change its Storage to external, and save it to a path like: path/to/.../custom_frameworks/dita-extension/dita-extension.framework.
6. Make whatever changes are necessary to the framework configuration, and in the Author tab click the CSS tab and add a reference to your custom CSS. Do not set a title for the CSS and also do not check the Alternate checkbox as you want your CSS to be applied by default.
7. Click OK to close the dialog box and then either OK or Apply to save the changes to the preferences.

After you perform these steps, you will have a fully functioning framework in the dita-extension folder that can be shared with others: Document Type Extension Sharing.

To check that your framework extension works, you can create a new DITA topic and insert a dl element inside it. It should now be presented in a table-like layout.

In order to know which CSS styles to override for a specific DITA element, you can right click inside that element in the Author visual editing mode and use the Inspect Styles action to see all CSS styles defined for it by default. You can also define alternate CSS styles that are applied manually by the writer by using the Author toolbar Styles drop-down menu.