- Git - make sure your Privacy & Security settings allow to download applications from anywhere
- SSH key associated with GitHub.
- Test access with
ssh -T git@github.com
- see here for help.
- Test access with
- Node.js — Latest Active LTS: See Release schedule(e.g. v8.11.3)
nvm install
will get the correct version to use from.nvmrc
.- You should run this at the start of your session to ensure the correct version is in use.
- The version can be verified by running
node --version
- Markdown capable editor: e.g. Atom, Sublime Text or similar.
- The Atom Documentation plugin-This plugin provides suggestions for {{file ...}} and {{page ...}} links.
- EditorConfig plugin (Recommended)
- Install homebrew (http://brew.sh/) and run
# Update
brew update
# Install git and libsass
brew install git libsass
Clone the repository to your local machine, using your favorite Git client or the command line:
git clone https://github.com/nuxeo/doc.nuxeo.com
cd doc.nuxeo.com
npm install
npm start
npm run server
npm run dev_server
Run a complete build so all pages are built.
npm start
To speed up the build you can comment out versions in config.yml
with #
. e.g.
repositories:
platform:
url: git@github.com:nuxeo/doc.nuxeo.com-content.git
branches:
- static
- master
# - '710'
# - '60'
# - '58'
710
, ,60
and 58
have been commented out so only the static content and FT platform spaces are built.
Then run the following to host and watch for client asset changes
npm run dev_assets
The browser defaults to chromium-browser
but can be changed with the following command and then locally as usual.
npm config set Nuxeo-documentation-content:browser firefox
As this module is used via npm, it's a good practice to bump the version when we make changes.
Node packages follow Semantic Versioning (SemVer), versions a described by a MAJOR.MINOR.PATCH
version.
Recompile the client assets
npm run compile
git add assets lib
git commit -m 'Client Assets: Recompiled'
After you've committed your code, run one of the following:
npm version major # incompatible API changes
npm version minor # add functionality in a backwards-compatible manner
npm version patch # backwards-compatible bug fixes
Then push the version commit and the tags:
git push && git push --tags
Any files in this directory will be copied to ./site/assets
. See ./site/...
Client side styles (SCSS) and JavaScript.
Templates and partials. See working with templates.
Nuxeo specific modules.
Generated output of the site. This is what will be served in production.
Unit tests for modules.
Verification tests for post asset and site building.
The main build script for generating the output for site
.
Site configurations, ability to have production or development specific values.
site.new_version: '{version number to match}'
forNEW
tagsite.review_period: '{number} {days, months, years}'
site.review_release_date: {date - YYYY-MM-DD}
Build processes are defined here. Should be relatively self explanatory but anything special will be explained here.
- Crawling configuration: https://github.com/algolia/docsearch-configs (specifically: https://github.com/algolia/docsearch-configs/blob/master/configs/nuxeo.json)
- Implementation Documentation: https://community.algolia.com/docsearch/documentation/
In the Content repository (doc.nuxeo.com-content):
Create branch (e.g. 910
):
# on doc.nuxeo.com-content
git checkout master
git pull
git checkout -b 910
Configure new branch:
- Open
./config.yml
- Update:
default > site > branch
default > site > dev_browser_path
default > site > versions
e.g.branch: '910' dev_browser_path: '910/nxdoc' versions: - label: LTS 2017 url_path: '910' is_current_version: true
Push new branch
git push --set-upstream origin 910
In the Builder repository (doc.nuxeo.com):
- Create a new branch from master:
git checkout -b add/remove-version-xx
e.g. adding 9.10 would begit checkout -b add-version-910
- Open config.yml.
- Add/Remove entry in
default > site > repositories > platform > branches
. - Rebuild to preview site.
- Merge into
master
to Go Live.
Code is licensed under a GNU GPLv3 and content
is under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.