dita-ot/website

DITA Open Toolkit project website · dita-ot.org

DITA Open Toolkit website

This repository contains the source files for the DITA Open Toolkit project website at dita-ot.org.

For details and background information on how we build and maintain the site, visit dita-ot.org/colophon.

---

If you'd like to set up a local staging environment and build a copy of the site, follow the instructions below.

• Environment setup
• Install prerequisite software
• Running Jekyll
• Building documentation output
• Updating JavaScript
• Happy staging!

Environment setup

1. Clone the DITA-OT and project website repositories:

   git clone https://github.com/dita-ot/dita-ot.git
   git clone https://github.com/dita-ot/website.git
   

   NOTE: The examples below assume the the DITA-OT and project website repositories have been cloned to a common parent directory, such as your home folder. If you clone the repositories to a different location, substitute that path for the tilde symbol ~ in the samples below.

2. Move to the DITA-OT directory:

   cd dita-ot
   

3. Fetch the submodules:

   git submodule update --init --recursive
   

4. In the root directory, run the Gradle wrapper to compile the Java code and install plugins:

   ./gradlew
   

5. Install the HTML plug-in for the DITA-OT project website: org.dita-ot.html

   src/main/bin/dita --install https://github.com/dita-ot/org.dita-ot.html/archive/master.zip
   

Install prerequisite software

1. Check if Ruby is installed:

   ruby -v
   

   Ruby is installed on macOS and most Linux distributions by default. If the command above does not respond with information on the installed Ruby version, see Installing Ruby for instructions. (Ruby 3.3 is required.)

2. Install Bundler:

   gem install bundler
   

3. Switch to your clone of the project website repository:

   cd ~/dita-ot-website
   

4. Install all of the required gems from the project’s Gemfile:

   bundle install
   

Running Jekyll

To build a copy of the site locally, use the bundle command to start the Jekyll build:

bundle exec jekyll serve

This runs the Jekyll build process and starts a local web server, so you can view your local clone of the project website at 127.0.0.1:4000.

At this stage, what you see there should be identical to the production version of the site at www.dita-ot.org.

Note: For more details, see Setting up your GitHub Pages site locally with Jekyll.

To refresh the page in your browser whenever source files change, pass the --livereload option:

bundle exec jekyll serve --livereload

Running Jekyll from Docker

Jekyll can also be run from a Docker image. No additional dependencies need to be installed:

docker run -it --rm -v $PWD:/website -e 4000 -p 4000:4000 ruby:$(head -1 .ruby-version) bash -c 'cd /website && bundle install && jekyll serve -H 0.0.0.0'

This runs a local copy of the project website at 127.0.0.1:4000.

Building documentation output

1. Switch to the docsrc submodule of the local dita-ot clone:

   cd ~/dita-ot/src/main/docsrc
   

2. Check out the develop branch of the docs repository to update the docsrc submodule pointer to the latest development state (or to another branch if you need to generate output for that):

   git checkout develop
   

3. Run the site build task with the Gradle wrapper to generate the output for the project website:

   ./gradlew site
   

The output will be generated by default in src/main/docsrc/build/site.

(This appears as unstyled HTML when viewed in place.)

To redirect the output to the dev development folder that Jekyll serves, pass the outputDir parameter to the build script as follows:

./gradlew site -PoutputDir=~/dita-ot-website/dev

After the build completes, you should find the results in the Docs > Development section of the local staging environment 127.0.0.1:4000/dev/.

To automatically regenerate the site output whenever documentation source files change, add the --continuous build option:

./gradlew site -PoutputDir=~/dita-ot-website/dev --continuous

Updating JavaScript

If you need to change any of the JavaScript files in the site repository, you'll need to download & install Node.js and run the npm package manager for JavaScript to perform a clean install of the project dependencies:

npm ci

This will install various Node modules including Parcel, the web application bundler.

To make changes to the JavaScript code, add or edit source files in the _js folder. You can then run the install script to compile the modified JavaScript code to the (ignored) js folder with Parcel:

npm run install

Happy staging!

You can now use the local staging environment to test your changes before committing your work.

When you're ready to share your progress, send us a pull request.

website's Issues

Update base URL for oXygen Web Author

💥 The base URL for oXygen Web Author has changed, so we need to update the Edit this page links to point to the new path on the server.

✅ — I have a fix available locally, planning to push that soon pending further testing…

Add to list of products that rely on DITA-OT

• oXygen XML WebHelp
• MiramoPlus DITA-OT Plugin

All information in the shared spreadsheet.

Syntax highlighting doesn’t run on page navigation

Expected Behavior

Syntax highlighting should be applied to code blocks when navigating between docs pages.

Actual Behavior

• Code blocks are highlighted on initial page load, but when a ToC link is followed, the new page loads without syntax highlighting.
• Highlighting is only applied when the page is reloaded with ⌘R or F5.

See @jelovirt #216 (comment) in the original pull request, and dita-ot/docs#272 (comment).

Add GitHub file history links to dev docs

In addition to the Edit this page links that open the source file for the current topic, and the Git commit metadata in the page footers, it would be helpful to provide links to the file history on GitHub, like in the oXygen 19.1 User Guide.

Sample footer content:

Page content generated from DITA source · Latest change: dita-ot/docs@905454b · File history

@georgebina I assume those links were generated via JavaScript, much like the edit links in EditController.js, but I wasn't able to locate the source file that calculates them. I see the v20.1 User Guide no longer includes these history links, so I'm wondering if you ran into issues with this approach.

In our case, the script code would need to re-use the logic from EditController.js to determine whether the source file is generated, and omit the history link in these cases, as generated topics are not versioned in the repository.

Update jQuery version

update suggested: jquery v3.0.0

Preserve redirects & messages topic

The redirect topics that were added in 2c2938f for #43 are removed in subsequent CI builds, since the dita-ot/docs/.travis/publish.sh script removes the target output directory before generating new output.

CI builds should be adjusted to preserve these topics, along with the auto-generated DITA-messages.html topic, which was removed by CI in d26b6f0 and manually restored in 713c090.

Plugins Page Not Loading

https://www.dita-ot.org/plugins does not seem work again. It seems it had some issue with loading the underlying JSON.

I have Mac OS X Mojave. I tried in both Google Chrome and Safari.

Here is log from Google Chrome Devtools. I also get a 404 / not found if I try to go to the URL
https://plugins.dita-ot.org/_all.json directly.

Failed to load resource: the server responded with a status of 404 ()
plugins:1 Access to fetch at 'https://plugins.dita-ot.org/_all.json' from origin 'https://www.dita-ot.org' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.
plugins.js:71 Failed to fetch plugins: TypeError: Failed to fetch

Use Algolia DocSearch

On December 1, 2016, @xephon2 wrote:

There is a free service called docsearch from a company called Algolia. You can use the service to get a small search box for searching the docs. Similar to what the DITA-OT docs does with DuckDuckGo, but more beautiful, because you don't have to leave the site.

You can see an example on https://facebook.github.io/react/.

Update list of products that use DITA-OT

We now have the go-ahead to list DITAweb and SDL Knowledge Center. The spreadsheet on Google docs is up-to-date.

Fix back navigation

Back navigation is broken.

Update documentation for plugins.xml

It seems there are a few elements in plugins.xml are updated.
For example, the http://www.dita-ot.org/2.1/dev_ref/plugin-newtranstype.html seems out dated. In plugins/org.dita.xhtml/plugin.xml, there's a new <transtype> element, with <param> elements underneath. I can't find any documentation on how they are used.

Publish the XSLT (or whatever) used to generate jekyl-ready html?

Hi, I'm looking to do something similar to what (I think) this site is doing: DITA -> HTML snippets w/ front matter metadata -> final, template'd HTML.

I see that files such as https://github.com/dita-ot/dita-ot.github.io/blob/master/2.0/index.html mention that they are converted from DITA, but I don't see the script/XSLT/whatever that's used to do the conversion - is that available anywhere? If not, could you publish it?

Update link to development builds

The Download page currently points to the GitHub Releases page:

Development versions

For the latest development versions, visit the DITA-OT Releases page on GitHub.

but we haven't been releasing milestone builds recently.

The link should be updated to point to the new develop distribution package on S3.

Migrate to ES6 and Parcel

Migrate code to use ES6 and Parcel.

Revise landing page

The dita-ot.org home page should be modernized to provide a more engaging first impression, highlight download and documentation links, and showcase third parties that use & support DITA-OT:

• Add list of vendors that bundle DITA-OT #21
• Add list of sponsors & supporters #22

Uppercase URLs break ToC on reload

Several source files in the docs still use uppercase letters in filenames. This worked without issue on GitHub Pages, but Netlify apparently tries to normalize the URLs, so on reload, pages with uppercase characters in their URLs revert to lowercase, and drop the .html suffix.

For example,

• https://www.dita-ot.org/3.3/reference/DITA-features-in-docs.html becomes
• https://www.dita-ot.org/3.3/reference/dita-features-in-docs

At the new URL, the full ToC is expanded in the navigation sidebar, like for orphan topics that are not present in the map.

Possible Solutions

• Verify whether pretty_urls can be disabled in Netlify admin panel (supposedly off)
• Replace remaining uppercase letters in filenames

Link from plugins page to registry & documentation

There is currently no link from the main plugin registry page at https://www.dita-ot.org/plugins to information on how to contribute.

A link to either the OT documentation topic or to the github repository itself would be very useful.

Continuous integration for `dev` docs

Implement a continuous integration solution to automatically republish the Development documentation on the project website at www.dita-ot.org/dev whenever changes are pushed to the develop branch of the dita-ot/docs repository.

Remove references to operating system specific packages

The page at http://www.dita-ot.org/download implies that there is one version (=download) of DITA-OT for Windows and another one for MacOS/Linux. This is not the case; when unpacked, the downloads are identical, the only difference is that one download is a zip-file, while the other is a tar.gz file.

I suggest to remove the references to the operating systems and just provide download links to the client package, maybe as simple as this:

• DITA-OT2.0_client_bin.zip [30.8MB]
• DITA-OT2.0_client_bin.tar.gz [29.7MB]

Use additional GitHub project metadata

To simplify site maintenance and streamline the release process, GitHub project metadata should be used wherever possible to dynamically point to the latest release info, binaries, contributors, etc, rather than linking to specific releases or files.

See https://github.com/blog/1996-releases-metadata-for-github-pages for more information.

Update footer when updating content

When JS updates content area on navigation, the footer is not updated.

Update landing page for 3.0

The landing page at dita-ot.org should be updated to reflect the changes in the 3.0 release.

Add AH Formatter to Print production list

Could you add AH Formatter to a list of Print production, please?

Best regares,

Keiko Hiraide
Antenna House, Inc.

Add DITA-OT 3.5 `install` syntax to plug-in pages

Description

The pages for each plug-in currently show 2 different syntaxes for installing each plug-in:

• for 3.2 and up
• for and 3.1 and older

implemented in plugins.js#L316-L322.

Possible Solution

Per discussion in 2020-04-02 contributor call, we should consider updating these pages to show 3.5 syntax by default, and provide syntax for older versions behind a <details>/<summary> disclosure toggle:

Show me more

More here.

Current Display

Install

DITA-OT 3.2 and newer

dita --install org.lwdita

DITA-OT 3.1 and older

dita --install https://github.com/jelovirt/org.lwdita/releases/download/2.3.1/org.lwdita-2.3.1.zip

Proposed Display

Install

DITA-OT 3.5 and newer

dita install org.lwdita

Instructions for previous versions

     DITA-OT 3.2 and newer

dita --install org.lwdita

DITA-OT 3.1 and older

dita --install https://github.com/jelovirt/org.lwdita/releases/download/2.3.1/org.lwdita-2.3.1.zip

Fix Bootstrap table classes

After the migration to Bootstrap 4 with #122, several tables in generated docs topics are no longer rendered correctly, most likely due to changes in the CSS classes that apply Bootstrap's table styles.

The fix is probably just a matter of remapping the new class names to the existing table classes.

Hide old docs versions from search engines

To provide more focused search results and ensure users find the latest docs versions, we should prevent search engines from indexing older docs versions by adding the versioned docs folders to a robots.txt file.

Deactivate DuckDuckGo HTTPS

Please set the param kh to -1 (off) in header.html#L43, see https://duckduckgo.com/params for explanations.

@jelovirt said:

dita-ot.org doesn’t have an SSL certificate, thus you can’t use it over HTTPS

Add list of vendors that bundle DITA-OT

To provide greater visibility of DITA-OT usage within the DITA ecosystem, the website should include a list of CCMS, editors, and other tools that bundle/embed DITA-OT.

This list could be featured on the landing page, possibly with vendor logos (like https://playframework.com/#references, or other open-source projects that highlight companies using their solution).

We might also want to include a list of customer companies that use DITA-OT in their publishing toolchains, though this list is likely to require a separate page.

Add site search field

The project website at www.dita-ot.org should include a Search field that allows visitors to search the contents of the DITA-OT documentation.

To avoid clutter & return latest content first, the site search should default to searching the documentation for the current release.

Consider implementing a mechanism that would allow visitors to refine searches to yield results from earlier versions, or select a version to search.

Change Miramo product name & link

Hi,

Could you change the name of our product & our link on the homepage of http://www.dita-ot.org/ ?

From MiramoPlus DITA-OT Plugin

to:

MiramoPDF

and change our link to:

http://www.miramo.com/download/documentation/Miramo_DITA-OT_Readme.pdf

Thank you so much for your assistance.

Kind regards,

Joanne Hannagen

Update listing for Bluestream XDocs CCMS

our XDocs CCMS isn't in the list could it be added please

Many thanks

Rik Page
EMEA Sales & Marketing Director
[phone]

More suggestive download buttons

When downloading DITA OT: http://www.dita-ot.org/download
it bothers me that those "Windows" and "Mac OSX and Linux" buttons look more like non-clickable labels and not download buttons. Maybe each of them could have a download icon...
Or at least name the buttons "Download Windows" and "Download Mac...."

Add list of sponsors & supporters

The website should include a list of Sponsors and Supporters to provide recognition to the vendors, institutions and individuals who provide ongoing support for DITA-OT development through employee contributions, sponsoring DITA-OT Day, etc.

Like the vendor listing for #21, this list could be featured on the landing page with sponsor logos that link back to the organizations that support us.

Add Eclipse as a DITA authoring environment

https://www.dita-ot.org/ has a list of authoring environments. Eclipse is missing.

Add FAQ

A DITA-OT FAQ is needed. The list should be about a dozen questions long.

Format your suggestion as

## Question

Answer.

Review & consolidate contribution information

Information on how to contribute to the project is currently divided between several pages:

• http://www.dita-ot.org/get-involved (in global navigation bar, renamed to contributing in a1b2313)
• http://www.dita-ot.org/participate (in sidebar)
• http://www.dita-ot.org/contribution_policy.html (link in Participate page)

This information is somewhat outdated and should be combined and edited for clarity.

Per discussion in July 7 contributor call:
https://github.com/dita-ot/dita-ot/wiki/Meeting-minutes-2016-07-07.

Set up ESLint and Prettier

Lint and format source files with ESLint and Prettier.

Add Husky pre-commit hooks per https://github.com/lipis/prettier-setup.

Migrate to Bootstrap 4

• Update templates, includes & static HTML files based on the Bootstrap 4.2 migration guide, including:
  • Replace panels & wells with cards per components
  • Update list groups
  • Replace Glyphicons with Font Awesome, Open Iconic or similar alternative icons
• Update site plug-in to generate Bootstrap 4 classes
  • Port old docs versions to Bootstrap 4

Add TopLeaf to list of print production products

Official name of product: TopLeaf XML Publisher
URL: http://www.topleaf.com.au
email: [email protected]
Contact: Shirley Keating

Automate dependency updates with Dependabot

Dependencies were updated manually for #46, but this process can be automated to ensure security vulnerabilities are quickly patched and other utilities such as Prettier keep up with the latest versions.

Dependabot creates pull requests to keep your dependencies secure and up-to-date.
— https://dependabot.com

The pull request process makes it easy to test updates before merging to production.

Run Prettier on HTML templates

After Prettier was set up with #45, v1.15 has since added support for HTML.

To ensure consistent formatting and quieter diffs, Prettier should be enabled for our HTML templates, includes & static HTML files.

• Ignore versioned docs subfolders with generated HTML output
• Verify Liquid tag support (see prettier/prettier#4484)
• Ignore templates with Liquid control flow tags pending resolution of prettier/prettier#5680
• Add to NPM scripts
• Add to Husky's pre-commit hook

Move 'Edit this page' button to dev docs banner

The docs survey by @lief-erickson revealed that many users are unaware they can edit docs topics with Oxygen XML Web Author.

To make this option more visible, the Edit this page button should be moved to the top of the page and placed within the dismissible banner that is shown on all pages of the development documentation.

Add “Edit this Page” footers

Per @georgebina's suggestion at DITA Europe, DITA-OT docs on the project website at www.dita-ot.org could include a footer with links that would allow readers to easily contribute fixes via the oXygen web app.

Functionality prompts users to sign in with GitHub credentials, forks repo if necessary, links may enforce branch creation to facilitate pull request workflow.

Sample copy:

“ This page is generated from a [public file on GitHub] – pull requests with improvements are welcome: [Edit page source].”

Plugins page is empty

The new plugins page is empty.

IE console:

DOM7011: Der Code auf dieser Seite hat die Zwischenspeicherung für das Vor- und Zurücknavigieren deaktiviert. Weitere Informationen dazu finden Sie unter: http://go.microsoft.com/fwlink/?LinkID=291337
Datei: plugins
HTML1300: Navigation wurde ausgeführt.
Datei: plugins
SCRIPT5009: "fetch" ist undefiniert
Datei: plugins.js, Zeile: 1, Spalte: 1713

Firefox console:

Die Ressource auf "https://ssl.google-analytics.com/ga.js" wurde blockiert, weil der Tracking-Schutz aktiviert ist.[Weitere Informationen]
plugins
Laden fehlgeschlagen für das <script> mit der Quelle "https://ssl.google-analytics.com/ga.js".
plugins:1
Failed to fetch plugins: TypeError: (intermediate value).flatMap is not a function
plugins.js:1:1816
<anonym>
https://www.dita-ot.org/js/plugins.js:1:1816

Add redirects for relocated topics

With the new top-level structure of the documentation for dita-ot/docs#121, the file system locations of many topics will change between 3.0 & 3.0.1 when dita-ot/docs#185 is merged with the hotfix/3.0.1 branch.

Although few deep links to 3.0 topics are likely to have been shared so soon after the initial release, several have already been sent via email and other channels, so redirects should be set up to automatically load (at least these) topics from their new locations.

GitHub Pages does not support redirecting via server configuration files such as .htaccess or .conf, but recent versions of the gem do support redirects via the jekyll-redirect-from plugin, which serves HTML files with an HTTP-REFRESH meta tag that points to the new destination.

As the name suggests, the plugin’s default usage is to add redirect_from metadata to the YAML header of files that should answer to alternative URLs, so the file that includes these entries is loaded instead. This approach is less useful in our case, where files are auto-generated from a common layout template, so individual overrides are less practical.

However, the plugin also supports a lesser-known redirect_to mode that can be used to set up (otherwise empty) pages at the old location with a YAML front-matter block that points to the new location:

---
# Redirect from old permalink
layout: base
title: Moved to new location…
redirect_to:
  - /3.0/topics/migration.html
---

I have verified this approach in local testing, and plan to roll out the changes with the 3.0.1 hotfix.

Clickable chapter rows on docs landing page

The topic overview on the docs landing page was updated with Bootstrap list group presentation in dita-ot/docs@6ce2c9d.

The hover effects create a button-like appearance for each list item, which should be extended with additional classes to expand the link target to the full width of each row.

Making the entire surface of each item actionable would facilitate entry navigation on touch platforms and make the link previews in short description tooltips more discoverable.

Add GitHub source file links to dev docs

To complement the existing commit ID links and GitHub file history links in #124, the “DITA source” portion of the dev docs footers could be extended to include a link to the current state of the corresponding source file.

Sample footer content:

Page content generated from DITA source · Latest change: dita-ot/docs@905454b · File history

This would either need to be implemented in JavaScript based on the logic in the EditController to pick up the correct path to the source file, or require an extension to the site plug-in to include the original source file name in the YAML header of the generated output files.

Use Bootstrap Sass instead of CSS

Rather than importing individual Bootstrap CSS files in the base.html layout, we should switch to the official Sass port of Bootstrap from https://github.com/twbs/bootstrap-sass.

This would allow us to import Bootstrap mixins in our main.scss file to style both static page content and DITA elements in the documentation output.

HTTPS redirect errors

When served via HTTP, DNS settings currently forward the naked root apex domain http://dita-ot.org to the secure variant with the www subdomain: https://www.dita-ot.org.

However, HTTPS connections to the apex domain https://dita-ot.org are currently refused, and an error message appears in the browser.

Thus far, we have not enabled strict transport security via the Enforce HTTPS option, relying on forwarding alone to prefer secure connections.

Forwarding settings in the DNS console should be verified to resolve several issues and prefer secure connections when possible:

• http://dita-ot.org → https://www.dita-ot.org
• https://dita-ot.org → 💥 CONNECTION REFUSED (should also point to https://www.dita-ot.org)
• http://dita-ot.org/3.1/release-notes/ → http://www.dita-ot.org/3.1/release-notes/
  (adds www., but should also point to secure variant)
• http://dita-ot.org/3.1/release-notes/ → https://www.dita-ot.org/3.1/release-notes/

Add PDF-ML to print production list

Would it be possible to add 'Antenna House' to the company listing at http://www.dita-ot.org/ ?
In addition to Formatter, which is used as one of the DITA PDF renderers, we created and maintain the PDF5 DITA plugin: https://github.com/AntennaHouse/pdf5

Thanks!

Angelo Cano