Import DITA's XHTML Output into WordPress
I've been working on some updates to the WordPress DITA Import tool. This tool allows you to import the DITA XHTML output into WordPress. For the full instructions, see this page on my demo site: Import DITA's XHTML Output into WordPress.
I've mentioned this tool before on my blog, but I've made some updates to the tool:
- Created a way to include the TOC navigation from the XHTML import automatically.
- Changed the installation method so that updates to WP won't overwrite the tool.
- Fixed some paths for images for both single and multisite.
- Corrected paths for absolute and relative links.
- Fixed an out-of-date WordPress tag for WP multisite.
- Included detailed instructions on how to use the tool.
The DITA import tool is fully compatible with the latest version of WordPress (4.0x). (Note that I didn't develop the original tool -- Mike Little did. I'm just making small modifications to it.)
The https://idratherbewriting.com/wpdita site has a demo of the DITA content imported into the Twenty Twelve WordPress theme. It's a minimalist theme, intended to be minimalist so that you can brand it to match your company's theme.
When you look at the site, pay special attention to the navigation sidebar (on the left). This navigation issue has been the most grizzly part of the import. I'm happy to say that the navigation is now mostly automatic. (On the first import, you just have to get the page ID and plug it in somewhere. You don't need to do anything on subsequent imports because each import overwrites the content of the existing page.)
The other big fix is that your upgrades to WordPress won't overwrite the import tool files. (Remember that this tool isn't a plugin; it's a file you add to your WP files.)
As a disclaimer, I haven't used this DITA to WordPress Import tool in an actual project, but I'm planning to.
Why use WordPress as a doc platform?
Why would you want to use WordPress as a publishing platform for documentation? Simply, most of the good documentation sites today are full websites. If you browse the list of API doc sites at http://www.programmableweb.com/apis/directory, you'll notice that most of the attractive doc sites are websites, not tripane help outputs. It makes sense to use WordPress as a doc platform because it gives you an easy way to set up a website with a modern looking theme and functionality (e.g, jQuery, Ajax, CSS3, HTML5). You can build your site to fit right into the web 2.0 landscape without being a front-end developer. For your doc content, you author in your local machine using an XML editor and then import the content into WP when ready.
In other words, the WordPress site is a shell for your DITA content, which is dynamic and changing. With the WordPress site, once you set it up, you can mostly leave it alone.
You can include a host of other features in your doc site that live outside of this content lifecycle. For example, you might add a contact form, a live search plugin, popular pages widget, related results, forums, social networks, Q&A features, comments, RSS feeds, news, and more. You can't really include all of these extra features if you're creating and tearing down your site with each new build. That's a major advantage of using WordPress over a static site generator.
Additionally, you can include content that isn't part of your DITA workflow. For example, suppose you have support agents who want to add KB articles, which you'll eventually convert over to DITA. You can accommodate these KB articles with the WP site. The DITA import doesn't blow away all your content with each import. Instead, it creates a new version of any existing page whose permalink matches the file name you're importing).
No doubt static HTML files load faster than a database model, but as long as you keep your WP site minimal, you shouldn't experience load times of more than a couple of seconds per page.
Let me know if you have feedback, requests, or suggestions for improvement. If you'd like to get involved in enhancing the theme or import tool, let me know. Again, all the details are here: Import DITA's XHTML Output into WordPress.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.