NativeScript Documentation

Home of the NativeScript documentation content that lives at http://docs.nativescript.org. Start contributing today!

Contributing 🍺
About Jekyll 🔩
Configuration ⚙️
Tutorials 📖
Local Setup 💻
Contributors ❤️

Contributing

The NativeScript documentation is completely open source and we love contributions. Whether you want to fix a typo, or write an entire article, the NativeScript documentation is a great way to get started contributing to an open source project.

Don’t know where to start? Check out the list of issues with the “up-for-grabs” label. New to git or GitHub? Join our community Slack chat and we’ll be happy to help get you up and running.

The master branch contains the most up-to-date version of the NativeScript documentation and its contents are uploaded to docs.nativescript.org. When contributing to the documentation, always create a branch for your work from master as this will facilitate easier pull request management.

About Jekyll

This documentation is built using Jekyll. More info on how to control the template, table of content and the project structure in general can be found in the Build README

Configuration

There are two versions of the NativeScript documentation that generate similar output: nativescript and angular. The former builds the vanilla NativeScript docs at docs.nativescript.org, while the latter discusses Angular-specific topics at docs.nativescript.org/angular.

Most of the content in this repository is shared between the two environments, but occasionally you may need to add environment-specific content. When you have this need you have a few options.

If you would like a page to appear in a single environment, add an environment: angular or environment: nativescript property to that page's front matter. Pages marked with an environment property will appear in a single environment, and pages not marked with an environment property will be shared across all environments.
If you have a page that should be appear in both environments but has different content for certain sections, you can use our built-in environment block tags. The blocks are named angular and nativescript, respectively, and can be used like this:

{% nativescript %}This paragraph appears only in the vanilla NativeScript documentation{% endnativescript %}

This paragraph appears in both environments.

{% angular %}This appears only in the Angular NativeScript documentation{% endangular %}

Tutorials

The NativeScript documentation contains two full getting started tutorials, one for using NativeScript with vanilla JavaScript, and another for using NativeScript with Angular. The contents of these two tutorials are in this repository’s /tutorial folder.

When making changes to either of these tutorials you might need to additional alter one of the four templates these tutorials use. Readers use these templates through the tns create command, for example tns create HelloWorld --template nativescript-template-tutorial.

JavaScript
- nativescript-template-tutorial
  - Hello world template used by the JavaScript tutorial.
- nativescript-template-groceries
  - Starting point for the Groceries example used by the JavaScript tutorial.
Angular
- nativescript-template-ng-tutorial
  - Hello world template used by the Angular tutorial.
- nativescript-template-ng-groceries
  - Starting point for the Groceries example used by the Angular tutorial.

Local Setup

If you plan to work on a non-trivial change, you will most probably want to run the documentation locally in order to give your change a try before submitting a pull request. To provide you with this opportunity without installing a ton of libraries and loose time in configuration, we have prepared a virtual environment based on vagrant configuration, where everything is prepared for you in advance.

Prerequisites

VirtualBox: https://www.virtualbox.org
Vagrant: https://www.vagrantup.com

Installing the virtual machine

Open a console box (Windows users should run a Git bash session!) and cd to the build folder of the working dir.

$ cd build

Then do a:

$ vagrant up

This should download the correct image, install it, start the VM and run the provisioning script.

Provisioning

The provisioning script (provision/install.sh) installs:

Base system packages;
Ruby;
Node.js;
nginx.

It also sets up the Jekyll project by installing all gems locally using bundler.

Building the documentation

Connect to the running VM first:

$ vagrant ssh

Then go to the project dir (mapped to /vagrant):

$ cd /vagrant

And run the build script telling it to use the current branch and avoid committing changelogs:

$ ./build.sh

Adding content

Edit an article and trigger your build by running build.sh as described above.

Then open a web browser on your host machine and navigate to http://localhost:8000/start/introduction.html or http://localhost:8000/angular/start/introduction.html.

Alternatively you could run a quick build with just a single configuration: "nativescript" or "angular" that will take about half the time. It could be useful when editing a documentation article and you want quicker feedback: