Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dita-ot/website
DITA Open Toolkit project website · dita-ot.org
https://github.com/dita-ot/website
dita dita-ot documentation documentation-tool hacktoberfest html jekyll jekyll-website publishing
Last synced: about 6 hours ago
JSON representation
DITA Open Toolkit project website · dita-ot.org
- Host: GitHub
- URL: https://github.com/dita-ot/website
- Owner: dita-ot
- License: apache-2.0
- Created: 2013-07-13T09:35:58.000Z (about 11 years ago)
- Default Branch: master
- Last Pushed: 2024-09-23T22:16:24.000Z (4 days ago)
- Last Synced: 2024-09-24T03:01:48.589Z (4 days ago)
- Topics: dita, dita-ot, documentation, documentation-tool, hacktoberfest, html, jekyll, jekyll-website, publishing
- Language: HTML
- Homepage: https://www.dita-ot.org
- Size: 31.9 MB
- Stars: 13
- Watchers: 7
- Forks: 24
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: contributing.md
- License: LICENSE
- Support: support.md
Awesome Lists containing this project
README
# DITA Open Toolkit website [](https://app.netlify.com/sites/dita-ot/deploys)
This repository contains the source files for the **DITA Open Toolkit** project website at [dita-ot.org][1].
For details and background information on how we build and maintain the site, visit [dita-ot.org/colophon][2].
---
If you'd like to set up a local staging environment and build a copy of the site, follow the instructions below.
- [Environment setup](#environment-setup)
- [Install prerequisite software](#install-prerequisite-software)
- [Running Jekyll](#running-jekyll)
- [Building documentation output](#building-documentation-output)
- [Updating JavaScript](#updating-javascript)
- [Happy staging!](#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][3] 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][4] for instructions. _(Ruby 3.3 is required.)_
2. Install [Bundler][5]:
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][6] 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][7].
At this stage, what you see there should be identical to the production version of the site at [www.dita-ot.org][1].
**Note:** For more details, see [Setting up your GitHub Pages site locally with Jekyll][8].
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:
```shell
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][7].
## 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/][9].
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][10] 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][11], 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][12].
[1]: https://www.dita-ot.org
[2]: https://www.dita-ot.org/colophon
[3]: https://www.ruby-lang.org
[4]: https://www.ruby-lang.org/en/documentation/installation
[5]: https://bundler.io
[6]: https://jekyllrb.com
[7]: http://127.0.0.1:4000/
[8]: https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/
[9]: http://127.0.0.1:4000/dev/
[10]: https://nodejs.org/en/download/
[11]: https://parceljs.org
[12]: https://help.github.com/articles/about-pull-requests/