Edit online

Contributed by: Radu Coravu on 2020-01-14

Our blog contains various useful articles and tutorials covering various aspects of editing, developing, and publishing using Oxygen XML Editor with various XML technologies.

Sometimes (quite often actually) articles originally written for the blog are curated by our technical writers and end up being part of our official documentation: https://www.oxygenxml.com/doc/ug-editor/. However, the blog allows us to deploy various small articles faster, without the need to wait for documentation updates.

History of the Oxygen XML Editor Blog

The blog was originally hosted by Google Blogs and the first articles on the blog appeared around 2007. Since Google Blogs did not allow enough flexibility in creating the published content (for example, the inability to create a table of contents) the blog was migrated to XML content and is now hosted on the Netlify platform: https://oxygenxmlblog.netlify.com/.

How the Oxygen XML Editor Blog Works

The entire source code of the Oxygen XML Editor blog is stored in DITA content on a public GitHub repository: https://github.com/oxygenxml/blog.

There is a Gradle build file that uses a special DITA Open Toolkit to produce WebHelp Responsive, EPUB and PDF outputs from the DITA content. The following features are available in the published output:
  • Color themes can be easily changed with CSS to modify how the output looks.
  • Search functionality. Possibility to add index terms.
  • RSS Feed is automatically generated from the entire list of topics.
  • PDF output is automatically generated using Oxygen Chemistry Engine and can be customized with CSS.
  • EPUB output is automatically generated using DITA For Publishers plugins.
  • Each page has an Edit online link allowing it to be edited in the Oxygen XML Web Author.
  • Each page has a comments section build using the Oxygen Feedback platform.
  • A validation report of the DITA content (reporting for example broken links) is available along with the published output: https://oxygenxmlblog.netlify.com/validationReport.xml.

How You can Contribute to the Oxygen XML Editor Blog.

We want to encourage our end users and collaborators to start creating small Oxygen-related articles for our blog. To post your own articles, follow these steps:

  1. Create your own GitHub account, if you do not already have one.
  2. Fork the contents of the Oxygen XML Editor GitHub project in your own GitHub Repository: https://github.com/oxygenxml/blog.
  3. Make changes to your forked project or to a branch from it.
    • If you have the Oxygen XML Editor application installed, you can download our Git add-on that should allow you to clone the fork, make changes, and then commit and push them to your repository.
    • As an alternative, you can use the Oxygen XML Web Author browser editing tool that has its own Git connector: https://www.oxygenxml.com/oxygen-xml-web-author/app/oxygen.html.
    • Please remember to add the name of the author and the created date for the topic in the DITA topic prolog section like:
      <prolog>
          <author>Radu Coravu</author>
          <critdates>
              <created date="2020-01-14"/>
          </critdates>
      </prolog>
      This prolog section will be used to add in the published HTML output the author information after the topic title.
  4. After all changes have been made to your fork of the project, you can create a pull request to the Oxygen XML Editor original GitHub project.
  5. We will review your changes and if your pull requests is accepted, the blog web site will be automatically updated with the new changes.

Technologies Used to Store, Build and Publish the Oxygen XML Blog

  • The blog content is stored on a public GitHub repository.
  • GitHub's issues list is used to organize the work and add new improvement ideas.
  • Offline editing the blog is done using Oxygen XML Editor with its Git add-on installed.
  • Online editing is done using Oxygen Web Author.
  • A Gradle build file is used to download a custom DITA Open Toolkit which contains the Oxygen WebHelp Responsive and PDF CSS plugins pre-installed, then run the publishing and validation stages.
  • The DITA Open Toolkit is used along with custom plugins to publish the DITA content.
  • Oxygen DITA Validate and Check for Completeness is run on the server side with the help of a special scripting license.
  • Netlify is used to connect to the repository, run Gradle and publish the WebSite.