DITA: Import DITA's XHTML Output into WordPress

1. Download the ditaimporter.zip file here and unzip it.
2. Upload the ditahelp.php file to wp-content/ditaimporter in your WordPress file structure. (Create the ditaimporter folder.)
   You can actually store this ditahelp.php file in other directories, but keeping it in wp-content is pretty safe because you never overwrite your wp-content folder when you update WordPress.
3. In a text file, create a new document and insert the following:

   <?php</span> include_once</strong>(ABSPATH . 'wp-admin/includes/import.php'</span>);
   require_once</strong>(ABSPATH . 'wp-content/ditaimporter/ditahelp.php'</span>);
                   

4. Save the file as dita-import-helper.php.
5. In your wp-content directory in WordPress, create a new directory called mu-plugins.
6. Upload the dita-import-helper.php file into that mu-plugins directory.

   mu-plugins stands for "must-use" plugins. mu-plugins work like regular plugins, except that they remain active even if you switch your theme or deactivate all your plugins. (You will never be prompted to update a must-use plugin, and they will still work even if you deactivate all your regular plugins.)

1. Create a new directory on your server called something like dita-staging.
2. In OxygenXML, duplicate the DITA Map XHTML transform.
3. Edit the DITA Map XHTML transform. Click the Parameters tab. For the args.html.toc parameter, type toc.
   If you leave the args.html.toc parameter at the default, the table of contents gets pushed into an index.html file, and the index.html file won't be imported. By changing the output file to toc, this file will be rendered as toc.html and will be included in the import into WordPress. The file's title will be your map file name (but its permalink will be "toc").
4. Transform your DITA content into XHTML and upload it to the dita-staging directory on your server using a tool such as FTP.
5. Find the absolute path to your dita-staging directory.

   One way to find the absolute path is by creating a file with the following contents:

   <?php phpinfo() ?>   

   Save the file as "phpinfo.php" and upload it to your dita-staging directory.

   View the phpinfo.php page in your browser. In the DOCUMENT_ROOT section, look at the absolute path. It will look something like this:

   /home2/idrathe1/public_html/

   Copy this path -- you will need in an upcoming step.

6. In WordPress, go to Tools > Import and click DITA help.
7. If you have a WP multisite, you have the option of selecting which site you want to import content into. Select the site from the Application Area selector. If you don't have WP Multisite, this drop-down doesn't appear.
   Note that with WP multisite imports, you always import content from your base site's admin directory. That is, you go to your_base_wp_url/wp-admin directory to run the import tool, rather than your_base_wp_url/subsite/wp-admin directory. Even for a multisite network of hundreds of sites, you always import your content from the same base site.
8. Leave the two check boxes ("Do you want to clear...?") unchecked. You use these to troubleshoot failed imports.
9. In the DITA help directory field, insert the absolute path to your dita-staging folder that you copied earlier.
10. Click Import Files. You will be prompted to move through about 5 import screens, and with each screen you click a button at the bottom to continue moving through the import.
    The import process is broken up into a series of steps to avoid memory issues (which probably become more apparent with imports involving thousands of files).

1. In WordPress, go to Appearance > Themes.
2. Activate the 2012 theme.
   If the 2012 theme isn't there, you may need to search for it and install it first. You can use other themes, of course. However, you will most likely have to do a lot of CSS work to get the theme in shape.

1. Go to Settings > Permalinks.
2. Click Post name.
3. Click Save changes.

# AllowOverride controls what directives may be placed in .htaccess files.
# It can be "All", "None", or any combination of the keywords:
#   Options FileInfo AuthConfig Limit
#
    AllowOverride All     

<Directory />
    Options FollowSymLinks
    AllowOverride All
</Directory>            

1. In WordPress, go to Appearance > Editor.
2. Click the functions.php file and add the following code at the absolute bottom of the file:

   remove_filter( 'the_content', 'wpautop' );
   remove_filter( 'the_excerpt', 'wpautop' );                     

3. Save the page.

1. Go to Appearance > Menus.
2. Type a name for the menu, such as Home.

3. Click Create Menu.
   You can add pages to this menu if you want, such as a home or contact page.
4. Select the Primary Menu location if you're using the 2012 theme.
   Different themes have different menu locations. If you're using a different theme, choose the location that corresponds to your primary menu.
5. Click Save Menu.

1. In the WordPress Dashboard, click the Pages section and open your toc file.
   Note: If you want to see more than 20 pages at a time, click Screen Options in the upper-right and change 20 to something like 100. Then click Apply.

   The toc file is your table of contents, and its name is the same as your map file name. In other words, it won't say "toc." It will say something like "DITA QRG." If you can't find it, go to /toc in your browser and edit the page that way.

2. While the page is in edit mode, look in the URL to find the page's ID. It will be a number such as 5 or 46 or something. Remember it.
3. Install and activate the PHP Code Widget plugin.
   If you don't know how to install and activate a plugin, it's pretty easy. Go to Plugins > Add New. In the Search Plugins field, type PHP Code Widget. Click Install Now next to the right result. After it installs, click Activate.
4. Go to Appearance > Widgets and add a PHP Code widget to your sidebar.
5. Add the following query to pull the toc page into a PHP Code widget:

   <div class="accordion clean">
   <?php
   $args = array</strong>(
   'page_id' => 104,
   );
   
   $the_query = new WP_Query( $args );
   
   // The Loop
   if ( $the_query->have_posts() ) :
   while ( $the_query->have_posts() ) : $the_query->the_post();
     the_content();
   endwhile;
   endif;
   
   // Reset Post Data
   wp_reset_postdata();
   
   ?>
   </div>
   </div>      

   In this example, 104 is the page ID of the toc page. Update this ID to the actual ID of your page. The tocPage ID accordion clean classes are essential for triggering the jQuery scripts.

6. Remove the other widgets you don't want by dragging them away.

1. Go to JQUERY VERTICAL ACCORDION MENU PLUGIN on Design Chemical Premium Plugins. In the upper-right (almost within the header itself), click Download.
   Note: Even though you're implementing this jQuery plugin into WordPress, do not use the WordPress version of this same plugin. The WordPress version of the plugin will require you to create a menu in Wordpress, which is not something that we can import through the DITA Import tool. If you create a menu in WordPress, it will be out of sync with the DITA content that you're importing.
2. FTP into your wp-content/themes/twentytwelve folder and upload the Javascript and CSS files that you downloaded. You should add the scripts to a folder called "js" and the styles to a folder called "css".
3. Go to Appearance > Editor and edit your header.php file. Before the closing tag, add the following references to the stylesheets and scripts:

   <!-- accordion start -->
   <link href="<?php echo get_template_directory_uri(); ?>/css/dcaccordion.css" rel="stylesheet" type="text/css" />
   <script type='text/javascript' src='<?php echo get_template_directory_uri(); ?>/js/jquery.cookie.js'></script>
   <script type='text/javascript' src='<?php echo get_template_directory_uri(); ?>/js/jquery.hoverIntent.minified.js'></script>
   <script type='text/javascript' src='<?php echo get_template_directory_uri(); ?>/js/jquery.dcjqaccordion.2.7.min.js'></script>
   <script>
   jQuery(document).ready(function($) {
   
    jQuery( "#tocPage ul:nth-child(1)" ).attr({
     class: "accordion"
   });
   
       jQuery('#tocPage ul:nth-child(1)').dcAccordion(
   {
   eventType: 'click',
   autoClose: false,
   saveState: true,
   disableLink: true,
   speed: 'fast'
   }
   );
   });
   </script>
   <link href="<?php echo get_template_directory_uri(); ?>/css/skins/clean.css" rel="stylesheet" type="text/css" />
   <!-- accordion end-->
                           

   If you read about the jQuery plugin, you'll see that I'm not using #accordion to trigger the plugin. Why not? Well, when the DITA OT converts the ditamap to an index file, it strips away all classes. In other tutorials (such as the DITA: Add an expanding side pane (Sidr)), I explained how you can edit certain source files in OxygenXML to allow classes to pass through. Unfortunately, these same edits don't affect the classes in the ditamap. No worries, though. We select the right element through a child combinator selection (#tocPage ul:nth-child(1)). This selects the first list that appears after the #tocPage ID.

   Also note that if you read about the options available in the jQuery plugin, you'll see that I've specified some here:

   eventType: 'click',
   autoClose: true,
   saveState: true,
   disableLink: true,
   speed: 'fast'                      

   Of note here are the saveState and autoClose options. The saveState option means when a user opens a menu and reloads the page, or actually goes to the page (meaning the site reloads), that menu stays open. You want this saveState option set to true so the user knows where he or she is at in the nav menu. (The jquery.cookie.js file allows for the saveState option to work.)

   The autoClose option determines whether the other sections close when you open another section (the accordion feature). Traditional accordions close other sections when you navigate them. I think leaving each section open makes the TOC menu look too big. You can read the Design Chemic documentation for the plugin to see what the other options control.

   Note: Unfortunately there's a glitch with the TOC that I didn't realize. If you click a link in a topic that opens another topic, that newly opened topic isn't automatically highlighted in the TOC.

1. Go to Settings > Reading.
2. In the Front Page Displays section, select a A Static page. Then select the static page you want, such as your help overview page.
3. If you want your blog posts to appear on another page, create a new page on your blog called "News" or something. Then return to this section and select the News page for your Posts page.

To get the latest styles:

1. Go to https://idratherbewriting.com/wpdita/, right-click, and choose View Page Source (this is the option in Chrome; it may vary for other browsers). Search for styles.css and then click it.

2. Search for tom's styles. Copy everything below this point.
   These are all the styles I've customized. Unfortunately, I haven't organized them very well. I mostly just add them as needed as I go along...
3. In your WordPress site, go to Appearance > Editor.
   By default, the style.css file should load in your theme editor.
4. Scroll to the bottom, insert the "tom's styles" content that you copied, and then save the file.
   You could also create a child theme, but since the WP 2012 theme isn't something that you'll probably be updating regularly apart from the custom theme, there's little reason to do this.
5. Grab the styles for the navigation skin ("clean.css") by following the same process you followed to get to styles.css. Copy the files in clean.css.
   Unfortunately you can't edit clean.css by browsing to it within your WordPress theme editor.
6. Using FTP, go to wp-content/themes/twentytwelve/css/skins and download the clean.css file.
7. Replace the contents with the styles you copied and reupload, overwriting the previous file.

1. Add the Table of Contents Plus plugin.
2. Go to Settings > TOC+.
3. Configure any settings you want, and then click Update Options.
   You may be tempted to choose Top for the Position. However, note that if you choose this, the Table of Contents will jump past your introduction if the user clicks the first heading in the content menu. That's why it's probably better to choose Before first heading (default). This is the same style that Wikipedia uses.