LoopBack project site - now with documentation!
Clone or download
Permalink
Failed to load latest commit information.
_data Deploy strongloop/loopback.io to github.com/strongloop/loopback.io.gi… Sep 19, 2018
_includes Add Google Analytics (#738) Sep 14, 2018
_layouts add a new line before end div tag (#721) Aug 1, 2018
api-explorer Deploy strongloop/loopback.io to github.com/strongloop/loopback.io.gi… Sep 15, 2018
contributing Fix typo for contributing Nov 16, 2016
css feat: discovery powered search and sitemap gen May 17, 2018
doc update release status (#710) Jul 20, 2018
examples Update for loopback-cli release (#254) Jan 20, 2017
fonts Add doc site POC Aug 2, 2016
getting-started Update index.html Jul 24, 2017
images feat: discovery powered search and sitemap gen May 17, 2018
js feat: discovery powered search and sitemap gen May 17, 2018
pages Deploy strongloop/loopback.io to github.com/strongloop/loopback.io.gi… Sep 22, 2018
resources Fix broken links; remove links to retired blog posts May 17, 2017
scripts-pdf add a new line before end div tag (#721) Aug 1, 2018
search feat: discovery powered search and sitemap gen May 17, 2018
users Add best practices for bottom up approach (#624) Mar 9, 2018
.gitignore chore: remove pages from .gitignore May 30, 2018
.markdownlintrc adding markdown linting script Oct 7, 2016
.npmrc Add a hosted swagger UI for LoopBack apps (#530) Nov 14, 2017
.travis.yml install gems on travis for build May 17, 2018
404.md Update TOCs to use toc_level and related Nov 11, 2016
CNAME Create CNAME Jul 5, 2018
CODEOWNERS Update CODEOWNERS Nov 10, 2017
Gemfile feat: discovery powered search and sitemap gen May 17, 2018
Gemfile.lock feat: discovery powered search and sitemap gen May 17, 2018
ISSUE_TEMPLATE.md Create ISSUE_TEMPLATE.md Sep 28, 2016
LICENSE Update LICENSE Nov 11, 2017
README.md feat: discovery powered search and sitemap gen May 17, 2018
_config.yml feat: discovery powered search and sitemap gen May 17, 2018
discovery-upload.js feat: discovery powered search and sitemap gen May 17, 2018
favicon.ico New favicon Oct 2, 2014
index.html fix LB4 link (#701) May 30, 2018
install Add installation helper script Apr 7, 2017
package.json chore: mark as a private package May 30, 2018
posts.json feat: discovery powered search and sitemap gen May 17, 2018
sitemap.js feat: discovery powered search and sitemap gen May 17, 2018
update-community-readmes.sh adds Supertest models project (#410) Jun 30, 2017
update-lb4-docs.js Fix update-lb4-docs to handle missing files (#704) Jun 15, 2018
update-readmes.sh update shell script for zosconnectee readme Aug 8, 2018
update-v4-readmes.sh doc add soap-calculator to lb4 readme files (#730) Aug 27, 2018

README.md

loopback.io

LoopBack community site, http://loopback.io. This website now includes the LoopBack documentation.

NOTE: The website is served from the gh-pages branch.

This repository is provided under the MIT License.

Setup

To preview the website locally:

  1. Install Ruby and Bundler if you don't have them already.

  2. Clone this repo (you might use the SSH URL instead of HTTPS).:

git clone https://github.com/strongloop/loopback.io.git
  1. cd to the repository directory and run the following command:
$ cd loopback.io
$ bundle install

Bundler will look in the Gemfile for which gems to install. The github-pages gem includes the same version of Jekyll and other dependencies as used by GitHub Pages, so that your local setup mirrors GitHub Pages as closely as possible.

Run and view site locally

Run Jekyll using the following command:

$ npm start

Then, load http://localhost:4001/ on your browser.

NOTE: The docs part will be at http://localhost:4001/doc. It's not yet linked from the main "overview" part of the site, but will be once we launch (RSN).

Formatting

Jekyll uses a variant of Markdown known as Kramdown.

Jekyll uses the Liquid template engine for templating.

Incorporating external READMEs

The documentation incorporates README files from a number of LoopBack example repositories. We use the get-readmes utility to fetch the README files directly from GitHub. Here is how to update the READMEs

  1. npm install (first time/setup only)
  2. npm run fetch-readmes

From there, the README markdown files are incorporated into documentation articles using the standard Jekyll "include" syntax as follows (for example):

---
title: "Angular example app"
lang: en
layout: readme
source: loopback-example-angular
keywords: LoopBack
tags:
sidebar: lb2_sidebar
permalink: /doc/en/lb2/Angular-example-app.html
summary: A brief tutorial on creating an Angular client app using the Loopback AngularJS SDK.
---

{% include readmes/loopback-example-angular.md %}

Incorporating updates from loopback-next

We use a node script update-lb4-docs to copy over contents from loopback-next repository using @loopback/docs package. The script is responsible for copying over the markdown documentation and related tables, as well as the sidebar used for LoopBack 4 content. The changes are then picked up as part of Travis CI's builds along with README update scripts and deployed to GitHub Pages once successful. The upgrade-swagger-ui.js script is also run as part of the builds. If you'd like to make documentation changes for LoopBack 4, please do so on its own repository.

Linting Readmes

There is an additional npm script that "lints" the readmes for markdown formatting problems. It is currently "experimental", see this issue for more info.

You can run this script thus:

$ npm run lint-readmes

LoopBack.io Docs Search

Docs Search is powered by IBM Watson Discovery.

How it works

LoopBack Docs are uploaded to Discovery by Travis CI (before deploying a new site -- after changes have been merged into gh-pages branch) automatically. The script creates a new collection and uploads each doc to that. The content of the docs along with certain metadata can be found in _site/posts.json. Travis uploads each Object in that file as a separate document (only uploads documentation pages).

Travis CI has encrypted variables which sets the environment variables for Discovery username / password. Core team can reach out to Taranveer Virk / Diana Lau for these credentials if needed.

  • Once docs have been uploaded, Travis will delete the previous collection as the Search URL uses the oldest collection available to serve results.

If you want to try this out locally, you can create an account for Watson Discovery (Use the Lite plan which is free). Set the following environment variables locally:

export DISCOVERY_USERNAME="username"
export DISCOVERY_PASSWORD="password"

You can now upload docs to your Watson Discovery instance by running

npm run discovery-upload

Front End

Each documentation page has a search bar the top. The search will redirect the user to a /search page to show the results. The results are retrieved from a IBM Cloud Function that acts as a proxy to protect Watson Discovery credentials. The search bar also contains a hidden form input that sets the sidebar value and Watson Discovery filters content based on this value to return context aware results. Ex: Searching for the word controller from a LoopBack 4 documentation page will return LoopBack 4 results. To search all documents you can search from the /search page. Community Docs and Contribution docs are included in all results.

Cloud Function

The code for the Cloud function can be found here. It is deployed to the same account and must be edited directly in IBM Cloud (formerly BlueMix). The repository exists to document code changes and have peer reviews. Credentials for accessing the Cloud Function can be obtained from Taranveer Virk / Diana Lau OR you can ask them to re-deploy changes.

Your own version

You can deploy the code on your own BlueMix account and upload the URL for Discovery in search.html. For the function to work, you must set the following parameters in the function settings:

discovery_username: username
discovery_password: password