DITA Open Toolkit website · dita-ot.org
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Add Probot Stale & No Response configurations Feb 6, 2019
1.8 Migrate Bootstrap classes in released docs Jan 4, 2019
2.0 Migrate Bootstrap classes in released docs Jan 4, 2019
2.1 Migrate Bootstrap classes in released docs Jan 4, 2019
2.2 Migrate Bootstrap classes in released docs Jan 4, 2019
2.3 Migrate Bootstrap classes in released docs Jan 4, 2019
2.4 Migrate Bootstrap classes in released docs Jan 4, 2019
2.5 Migrate Bootstrap classes in released docs Jan 4, 2019
3.0 Migrate Bootstrap classes in released docs Jan 4, 2019
3.1 Migrate Bootstrap classes in released docs Jan 4, 2019
3.2 Migrate Bootstrap classes in released docs Jan 4, 2019
_includes Add info on signing off earlier commits Feb 16, 2019
_js Adjust vertical spacing of plug-in filter form row Jan 30, 2019
_layouts Revert "Add banner to old docs versions" Jan 21, 2019
css Remove obsolete Sass partial Feb 17, 2019
dev Update ‘dev’ docs with Bootstrap 4 classes Feb 10, 2019
fonts/bootstrap Add icons to download buttons (Fixes #13) Apr 14, 2016
images Enable DITA-OT Day banner Jun 5, 2018
js Adjust vertical spacing of plug-in filter form row Jan 30, 2019
.browserslistrc Convert utility modules to TypeScript Dec 30, 2018
.editorconfig Add EditorConfig to help maintain coding style Mar 18, 2016
.eslintrc.yml Initialize ESLint & default to Airbnb style guide Jan 4, 2018
.gitignore Restore Gemfile Jan 21, 2019
.prettierignore Skip sidebar to prevent errors with nested lists Dec 26, 2018
.prettierrc Update Prettier options for JavaScript Jan 4, 2018
CNAME Create CNAME Nov 5, 2018
DCO.md Re-run Prettier to pick up latest v1.14 formatting Aug 7, 2018
Gemfile Restore Gemfile Jan 21, 2019
LICENSE Add standard Apache License 2.0 Oct 31, 2018
README.md Remove obsolete Gulp references & update ReadMe Jan 30, 2019
_config.yml Remove obsolete Gulp references & update ReadMe Jan 30, 2019
colophon.md Re-run Prettier to pick up latest v1.14 formatting Aug 7, 2018
contributing.md Update link to use new issue templates Oct 3, 2018
download.html Use Jekyll plug-in for Octicons Jan 10, 2019
google1bb01aaffe2c210e.html Run Prettier v1.15.3 on current files Dec 26, 2018
index.html Use Jekyll plug-in for Octicons Jan 10, 2019
jest.config.js Add Jest tests Dec 30, 2018
management.html Run Prettier v1.15.3 on current files Dec 26, 2018
package-lock.json [Security] Bump handlebars from 4.0.12 to 4.1.0 (#158) Feb 14, 2019
package.json Bump @types/jest from 23.3.13 to 24.0.0 (#157) Feb 11, 2019
params.json Remove articles, refactor claim Oct 3, 2018
plugins.html Use proper typographic ellipsis Jan 6, 2019
robots.txt Hide old docs versions from search engines #135 Jan 3, 2019
support.md Update support page, align copy & menu Oct 30, 2018
tsconfig.json Add Jest tests Dec 30, 2018
who_we_are.html Remove redundant row/column divs Jan 21, 2019

README.md

dita-ot.github.io

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

  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/dita-ot.github.io.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. Install Jekyll:

    gem install jekyll
    
  2. Install Bundler:

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

    cd ~/dita\-ot\.github\.io
    
  4. Install all of the required gems from the project’s Gemfile:

    bundle install
    
  5. Run Jekyll.

    bundle exec jekyll serve
    

    This runs the production version of the site locally, so you can view your local clone of the project website at http://127.0.0.1:4000/.

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

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

Building site 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.github.io/dev

After the build completes, you should find the results in the Docs > Development section of the local staging environment http://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.github.io/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 re-bundle the modified JavaScript code to the 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.