This repository contains the source code for the Cordova website. This covers cordova.io (= cordova.apache.org) and its subdomains docs.cordova.io (= cordova.apache.org/docs) and plugins.cordova.io (= cordova.apache.org/plugins).
- Introduction
- Table of Contents
- Installing
- Building
- Developing
- Deploying
- Working on the Documentation
- Adding a Tool or a Showcase App
- Writing a Blog Post
- Troubleshooting
- Attributions
Ruby 2.0 is required to build the docs. NOTE: The docs will not build with Ruby 1.8, 1.9 or 2.4.
Install Homebrew from this site, and then run:
brew install [email protected]
Follow these steps:
- Download this installer from this page.
- Run the downloaded file.
- Use the default installation path (usually
C:\Ruby22). - Make sure the 'add executable to path' option is checked.
- Use the default installation path (usually
- Download this Ruby DevKit self-extracting archive from the same website.
- Run the downloaded file.
- Use the following extraction path:
C:\Ruby22DevKit.
- Use the following extraction path:
- Open
cmd.exe.-
Go to the extraction path:
cd C:\Ruby22DevKit -
Run these commands (following any instructions they give):
ruby dk.rb init ruby dk.rb install -
Close
cmd.exe.
-
Run the commands from this site that apply to your Linux distribution.
Verify your Ruby installation by running:
ruby --version
Python 2.7 is also required to build the docs. NOTE: The docs will not build with Python 3.0 or greater.
Mac OS X comes with Python 2.7 pre-installed. Else, follow these steps:
- Download this installer from this page.
- Run the downloaded file.
Follow these steps:
- Download this installer from this page.
- Run the downloaded file.
- Use the default installation path
- Make sure the 'add executable to path' option is checked.
The latest version of CentOS, Fedora, Redhat Enterprise (RHEL) and Ubuntu come with Python 2.7 pre-installed. Else, follow the steps from this site.
Verify your Python installation by running:
python --version
The version must be 2.7.x.
Go to this site, and click the "Install" button. Then run the downloaded file and follow the on-screen instructions. Make sure that the option to install NPM is enabled, if you see one.
Linux, follow the instructions on this site.
Verify your Node.js installation by running:
node --version
npm --version
Once Ruby and Node.js are installed, install Ruby dependencies by running:
gem install bundler
bundle install --path ./ruby_modules
This will install the required Ruby Gems locally into a subfolder called ruby_modules in your repo folder. On some systems, the above commands need to be prefixed with sudo. Similarly on Windows, the cmd window in which those commands are to be run might need to have been "Run as Administrator."
Finally, install Node.js and JavaScript dependencies by running:
npm install
The website can be built with Gulp or Make. The Gulp workflow is enabled by just installing all the JavaScript dependencies. The Make workflow usually allows for faster builds, but requires installation of the make tool.
Make can be installed on Windows from this page by downloading the setup tool and running it.
Make comes with the Xcode Command Line Tools. To install them, run:
xcode-select --install
Make is installed by default on Linux.
Verify your make installation by running:
make --version
To build the whole website, run:
node_modules/.bin/gulp build --prod
The built website will be in a folder called build-prod.
To work on the website and see changes live as you save, run:
node_modules/.bin/gulp serve
That command will build the site and start a local server. To work on only the website without the docs, add the --nodocs flag, as follows:
node_modules/.bin/gulp serve --nodocs
Alternatively, to dynamically rebuild the site and refresh the browser when changes happen (again, optionally with the --nodocs flag), run:
node_modules/.bin/gulp watch
Sometimes docs pages get removed, renamed, and added. There is a file that contains redirects for such occasions. It has three sections:
docs-global: redirects across all docs versions and languages,docs: version-specific docs redirects, andgeneral: single-page redirects.
For non-docs URIs, there are no versioning considerations. Make redirects like so:
general:
- {old: "old/uri/for/page.html", new: "its/new/uri.html"}
NOTE: Review (and test, if possible) these redirects before making them live, since they're permanent (HTTP 301) redirects. Incorrect permanent redirects will make a URI almost impossible to bring back into browsers and search indices.
There are five cases of changing URIs:
- Adding a brand new (no past equivalent) URI starting at a version,
- Removing an old URI (with no replacement) starting at a version,
- Renaming (removing and adding) an existing URI starting at a version,
- Renaming an existing URI across all versions,
- Removing an existing URI across all versions.
Do nothing. Going back in time for new docs is unsupported.
If the URI is removed, mark it as deprecated in latest/ like so:
docs:
- {old: "latest/old/uri/for/page.html", new: "deprecated.html"}
If the URI is moved, point it to its new location in latest/ like so:
docs:
- {old: "latest/old/uri/for/page.html", new: "latest/its/new/uri.html"}
These will handle the case where the "this content is outdated" link is clicked. The case where a user jumps to a specific version is not yet supported.
Add the redirect (in the docs-global section this time) like so:
docs-global:
- {old: "old/uri/for/page.html", new: "its/new/uri.html"}
Do nothing. It is now an un-URI. It never existed. Mentioning it is thoughtcrime.
This section requires basic knowledge of SVN. If you do not know how to use SVN, refer to this tutorial.
To build the full website, run:
node_modules/.bin/gulp build --prod
A folder called build-prod will be created, and will contain the built website. Then, in a directory one level above the cordova-docs repository, check out the SVN repository that contains the currently deployed website by running the following command (committer access required):
cd ..
svn checkout https://svn.apache.org/repos/asf/cordova/site cordova-website
Then, move into the cordova-website repository and synchronise it with the SVN server:
cd cordova-website
svn update
Copy the cordova-docs/build-prod/ directory to the public directory in SVN like so:
cd ..
cp -R cordova-docs/build-prod/. cordova-website/public/
Some files will be new (? in SVN, and need to be svn added) and some files will be changed (M in SVN; no action required). To see just the ? changes, run:
cd cordova-website
svn status | grep "?"
Once you are satisfied that you have added the required changes, commit with a message:
svn commit -m "Updated docs"
NOTE: The commit might take a while (up to 1 hour), depending on the number of files changed.
Refer to this README.md for information about writing documentation.
Note: many changes to the overall documentation come from other repos and are simply pulled together by a build. tools/bin/fetch_docs.js has more details and www/_data/fetched-files.yml contains an informative list of src/dest pairs. Most auto-generated files have a comment tag at the top of the file to indicate that they come from elsewhere.
Items on the Codorva Tools or the Cordova App Showcase sections on the main page are modifiable by the public. Below are the guidelines and process to do so.
The display image shall:
- be less than 128KiB in size (NOTE: those are kibibytes, not kilobytes),
- contain the logo of the tool/app,
- use colors that don't compete with other elements on the page, and
- have acceptable measurements, as follows:
- 298px by 100px or smaller with a roughly rectangular aspect ratio for tools, and
- 100px by 100px or smaller with a square aspect ratio for apps.
The description shall:
- contain neutral and non-advertising language.
The name shall:
- be at most 40 characters long.
Showcase apps shall:
- be available for download on a public app store or website.
Furthermore, descriptions are stripped of HTML and are truncated to fit as follows:
- down to 255 characters for tools and,
- down to 200 characters for showcase apps.
- Change the section's YAML file:
- www/_data/tools.yml for Cordova Tools, or
- www/_data/showcase-apps.yml for Cordova App Showcase.
- Optionally add an image:
- Place the image in the section's
imgdirectory:- www/static/img/tools for Cordova Tools, or
- www/static/img/showcase-apps for Cordova App Showcase.
- In the YAML file, set the
imagefield to the file's name.
- Place the image in the section's
- Submit a GitHub pull request with the changes.
-
Pull down the latest website codebase for the current posts
git pull -
Create a new entry in the www/_posts directory.
-
Use an earlier post an a template. Edit your md file to remove undesired markdown links. If there is a phrase in square brackets that isn't a CB-xxxx reference, escape it with backslashes. Otherwise, heruko might error out and fail to build all the html.
[CB-1234] \[iOS\] \[Camera\] add a whizzbang to the snarfblat -
Set a marker where the summary on the home page should stop displaying. Add the following html comment line to your md file at the desired cutoff point:
<!--more--> -
In the front matter of your blog entry, set the
date:field to the desired date that you want to appear near the title. Be aware that the date (explicit here or implied via the filename) will be used to generate the relative path to this html file (e.g. "/announcements/2014/09/22/cordova-361.html"), as will thecategories:front matter value.date: 2014-09-22 categories: announcements -
Run gulp link-bugs to linkify
gulp link-bugs -
Preview it locally by running the site using gulp
-
Raise a Pull Request with the changes
Announcements - releases, call for translators, etc
Core Content - If the content has to do with cordova-core, or publishing guides, etc., we should publish the full text directly on the cordova Blog (by whichever author), as-if written by the organization.
Linked Posts - If the content was written by a contributor and is worth curating for the whole community, but is not really core ie. non-core plugins, dev tips, research, opinion-pieces, statistics, etc., post a short description, perhaps adding a document-snippet, but then link to the externally hosted content, making it clearly not written by the organization.
- Use the post title as the first header.
- Including a header as well makes the snippet on the front page look bad.
- Use an appropriate category:
- One of:
howto,news,releases,announcements,blog(the catch-all category) - Use appropriate tags:
tools,plugins,android,ios,windowsphone,blackberry,plugin-$FOO,cli,performance,last-week,security(add to this list as necessary)- Use gulp to preview your posts locally.
- Jekyll does a poor job telling you where markdown errors exist.
- Use the tag to specify the cutoff point for displaying your post on the main page.
- Review your post yourself before asking for a review. This includes spell-check :).
- Ask for a review by raising a pull request
To get a summary of changes (and count the changes):
for l in cordova-*; do ( cd $l ; git log --format="$(printf %30s $l) %s" --no-merges --since='1 week ago' ) ; done | grep -iv version | grep -v CHANGELOG > all_logs.txt
To get the number of authors:
for l in cordova-*; do ( cd $l ; git log --format="%an" --no-merges --since='1 week ago' ) ; done | sort | uniq | wc -l
Create a copy of a previous post and update it.
To print the list of plugin versions tested:
-
Make sure all plugin repos are cloned, updated, and on master branch
-
Run:
for d in *-plugin-*; do ( cd $d && echo "* $(basename $PWD): $(grep version plugin.xml|grep -v encoding|cut -d'"' -f2)" ) ; done | grep '^\*'
Increase the maximum number of open files on the system:
ulimit -n 10480
Run:
gulp clean
You could try a different method to install Ruby. Checkout rbenv. Instructions:
-
Install rbenv
brew install rbenv ruby-build -
Add
eval "$(rbenv init -)"to the end of your.bash_profile:echo 'eval "$(rbenv init -)"' >> ~/.bash_profile -
Install a version of
rubyand set it to your local version:rbenv install 2.0.0-p647 rbenv local 2.0.0-p647
Please ask for help on the Slack channel. Join at slack.cordova.io.
For attributions for used open-source work, please see the attributions page: www/attributions.html.