From #55:
Sometimes when left nav expands it goes too far and is unscrollable example you(I) cant see all the options.
If possible, we should fix this.

The website clearly lacks a big, visible link to the docs in the header. I had to read all the way to the bottom of the getting started page to finally find one (although I later found another one at the bottom of the main page) and it's kinda frustrating.

Why not have a menu that goes like Getting started Examples Resources Docs Who's using? Contributing ?
I'm sure I'm not the only one who has wasted a few precious minutes trying to find the docs. ;)

Are you planning spanish translations for the documentation? I don't see the option in the Translations menu

If so, i could help with that!

Issue templates

Some possible info to request (for this docs repo)

Maybe not all of this...

1. URL
2. Site bug or Content bug/errata
3. What was the content problem?
   • missing docs?
   • inaccurate docs?
4. What question were you looking for an answer for in the docs?
5. What change would you like to see? (what would "resolve" this doc issue?)

@altsang asked to replace the Sapient logo on the front page with B of A. So, we need to replace the Sapient logo in http://loopback.io/images/logo-collage.jpg with B&W version of https://strongloop.com/wp-content/uploads/2015/01/baml.png.

There are a few styling tweaks I would like. @Sequoia I can probably figure these out (when I can find the time) if I try, but if you can easily fix them, please do so.

There is a bit too much whitespace between the page content and the title bar (top bar). I know a certain amount of whitespace is good, but screen real estate is also valuable, so I just think we can bring it down by 10 - 20px or so...

The blue highlight that appears around a title in the navbar needs a little more space on the left--probably just a few px more padding:

Also, there is a small glitch in the top bar drop-downs:

The green highlight should extend all the way to the left edge of the "dropdown" (as it does on the right side).

Per @altsang we want to have a new "Contributing" page that will contain the info I added in 4d335a2 and a bit more. We will also need a "Contributing" navigation element in the header.

I haven't been able to figure out how to add a new nav element without screwing up the layout, so please @rosshj could you do this in a new branch? If you can add the nav element and new page, I can provide the content before we merge the PR. Please go ahead and merge the customers-tweaks branch first so that can be live while we're working on this.

gettalong/kramdown#374

How do I translate the files inside the folder (_ includes/readmes ) ?

We fetch the following READMEs into the docs:

• loopback-android-getting-started
• loopback-example-angular
• loopback-example-app-logic
• loopback-example-access-control
• loopback-example-angular-live-set
• loopback-example-connector", "branch": "remote
• loopback-example-connector", "branch": "rest
• loopback-example-connector", "branch": "soap
• loopback-example-database", "branch": "mssql
• loopback-example-database", "branch": "mysql
• loopback-example-database", "branch": "oracle
• loopback-example-database", "branch": "postgresql
• loopback-example-database
• loopback-example-kv-connectors
• loopback-example-middleware
• loopback-example-mixins
• loopback-example-offline-sync
• loopback-example-passport
• loopback-example-relations
• loopback-example-storage
• loopback-example-user-management
• loopback-example-isomorphic
• loopback-example-xamarin
• loopback-ios-getting-started

Need to make the following changes to these:

• Update any old links to http://docs/strongloop.com/... to be to http://loopback.io
• Ensure all links (e.g. to source files, etc) use absolute URLs, not relative, so the links work on this site as well as in GitHub.

The navgoco JavaScript nav widget has a number of limitations and issues, and we probably should just replace it with something else.

For the most part, the server-side part that turns the YAML sidebar file into an unordered list is working OK. One exception is that it doesn't allow 2nd-level items to have a URL, e.g. Creating model relations is a container but is not linked to an article.

At a minimum, it must:

• Create the nav from an HTML unordered list.
• Be responsive and work with Bootstrap.
• Be easy to change the display & make it look like we want.

There are dozens of possibilities, but https://www.jstree.com is a good candidate. See also http://1stwebdesigner.com/jquery-menu/ for a list of other possibilities.

Come up with a proposal to answer the following:

• What linter to use
  • Must support Kramdown
  • remark-lint suggested by @bajtos is a good place to start
• General Usage
  • Ad hoc (ie. npm run lint)
  • CI (ie. posttest: npm run lint)
• List of things to do during the actual tasks (ie. update readme with ad hoc usage instructions for loopback.io repo, submit PR with dep/integration with remark-lint, etc)

I ran into a roadblock working on #37. Jekyll/Liquid generates an error when processing includes with non-Western parameter values, e.g.

{% include important.html content="
LoopBackがどのように動くかを理解するには**まずこのページをお読みください。次に、LoopBack
アプリケーションを作成するための基本的な紹介として [Getting started with LoopBack]
(/doc/{{page.lang}}/lb2/Getting-started-with-LoopBack.html)
を参照してください。" %}

The error is:

Liquid Exception: Invalid syntax for include tag. File contains invalid characters or sequences: 
important.html content=" LoopBackがどのように動くかを理解するには**まずこのページをお読みく
ださい。次に、LoopBackアプリケーションを作成するための基本的な紹介として [Getting started 
with LoopBack](/doc/ja/lb2/Getting-started-with-LoopBack.html) Valid syntax: {% include file.ext 
param='value' param2='value' %} in pages/ja/lb2/LoopBack-core-concepts.md

The English content makes extensive use of Liquid includes (with parameters) for alerts and numerous other things. So we need to resolve this or find a workaround, otherwise it's going to be much more difficult to provide translations of the docs.

Before launch, it would be good to go through the content in http://loopback.io/doc/en/lb2/ and do thorough review for accuracy, completeness, formatting, etc.

• Did anything from https://docs.strongloop.com/display/LB/LoopBack get left out?
• Did anything get messed up in migration?
• Any formatting or layout glitches?

Figure out how to deal with content that we currently "transclude" (dynamically include) from other GitHub repos. Typically, these are example repo README files. We use a special Confluence macro to "single source" this content; we can do something similar with a Jekyll plugin, but there are wrinkles.

This is part of Proposal to make LoopBack documentation open source.

Related notes:

• http://jekyllrb.com/docs/plugins/
• https://www.sitepoint.com/jekyll-plugins-github/
• https://help.github.com/articles/using-jekyll-as-a-static-site-generator-with-github-pages/
• https://github.com/crandmck/crandmck.github.io for POC of remote markdown plugin.

We need a JavaScript widget that essentially duplicates the navigation panel on http://docs.strongloop.com. The source of the nav content will be nested lists in markdown and the result at runtime should be a nice "expandable" navigation widget.

This is part of Proposal to make LoopBack documentation open source.

Just before LB 3.0 release, need to:

• Copy the 2.x articles from pages/en/lb2 to pages/en/lb3, except (obviously) for the 3.0-specific pages that are already there.
• Rename any 3.0-specific articles to remove "3.0" from the title, e.g. Operation-hooks-version-3.0.html.
• Copy the 2.x sidebar nav to 3.
• Update pages/en/lb3/index.html to reflect release status, etc.
• Review the release notes to see if anything else needs to be updated in the 3.0 docs.

This will be a general issue to notify the community when we're ready to accept translation PRs.
See #37 for more details on localization.

Please comment here if you're interested in translating LoopBack docs so you'll receive a GH notification.

@dejaneves This issue replaces strongloop/loopback#2700 and I'll comment here when we're ready to accept translation PRs.

Create and add something similar to https://docs.strongloop.com/display/APIC/Search+LoopBack+docs to the new doc site.

It would be great if the auto-generated page TOC had these features:

• UI element to "minify" the TOC display. This would help esp. for long TOCs.
• Ability for author to specify that TOC displays only elements up to a certain level, eg. h1's only, or h1 & h2's only, etc. Sometimes you don't need to show all the lower-level headings.

This is minor, but all pages I've loaded are producing the following error on the console:

Uncaught TypeError: $(...).annotator is not a function

The offending code is the following page-end script,

    <script>
    jQuery(function ($) {
        $('.post-content').annotator()
                .annotator('setupPlugins', {tokenUrl: 'http://example.com/api/token'})
    });
    </script>

This does not appear to be impacting anything, but may be a sign of something missing/broken that you guys know about.

In addition to the English content (which is mostly migrated--still some work to do, but maybe 80% done atm), we need to migrate community-translated content from Confluence to Jekyll/Markdown in the following languages:

• Chinese: https://docs.strongloop.com/display/zh
• French: https://docs.strongloop.com/display/FR/LoopBack
• Japanese: https://docs.strongloop.com/display/JA/LoopBack
• Korean: https://docs.strongloop.com/display/ko/LoopBack
• Russian: http://docs.strongloop.com/display/RU/LoopBack

NOTE: even though we have https://docs.strongloop.com/display/PTBR, there doesn't seem to be any content translated into Portuguese, so there's nothing to migrate.

Several caveats:

• In every language, only part of the content has been translated, so we need to migrate only the translated articles.
• For untranslated content, we should just have the English content.
• Depending on the language, some/all titles in the sidebar navigation has been translated, and sometimes not.

ASAP, I will export the translated content, and (time permitting) run the migration script and check in the markdown files. If I run into problems, I may need to ask for help from @marc-ed-raffalli again :-)

I need to write up a short explanation about how people can contribute translations (for both existing and new languages). Cf #33.

Sidebar container items are left-indented more than items that are not containers:

The left-padding of these articles should be the same whether they are a container or not, because an item is at the same "level" in the hierarchy, regardless of whether it has children or not.

So, in the example shown here, the + for "Validating model data" should align with the beginning of "Exposing models over REST"

(I need to remove the duplicate "Defining models" item which is a leftover from the old scheme, but that's another matter).

Need to go through the site and find the pages for data source connectors that should be tied directlyt to module READMEs instead of a distinct md file. Then follow procedure in https://github.com/strongloop/loopback.io#getting-external-readmes to get the READMEs in the site.

Also: https://github.com/strongloop/strong-error-handler README --> http://loopback.io/doc/en/lb2/Using-strong-error-handler.html

Most of the articles need tags, per http://loopback.io/doc/en/contrib/tags.html.

We should use the same technique that we currently use to fetch the example repo READMEs to get the READMEs for all the data source connectors and the components. Also look at any other READMEs we should include into the docs.

This may require some minor modifications to the get-readmes code to allow for a second repos.json file in the _data directory.

The original Jekyll theme upon which the site is based provided for generating PDFs: http://idratherbewriting.com/documentation-theme-jekyll/mydoc_generating_pdfs.html.

However, we haven't tried doing this yet, and because we've made a number of changes to the overall infrastructure we may need to make some changes to get PDF generation to work properly.

i find all branch, there is nothing of en version page(only demo page).so i need to write the page all?�i'm confused...
please show me the guide. thank you

In http://docs.strongloop.com/display/public/LB/Add+a+static+web+page

/clientt/index.html => /client/index.html

and in second server/middleware.json snippet, the curly brackets does not be paired, that makes confusing.

Need to establish a framework for localization. This includes:

• Basic internationalization infrastructure along the lines of what we have at http://expressjs.com.
• Copying existing translations listed in https://docs.strongloop.com/display/public/LB/Docs+in+other+languages (as appropriate)
• Writing up procedure for translators to follow.

URL of the page

npm ERR! Windows_NT 10.0.10586
npm ERR! argv "C:\Program Files\nodejs\node.exe" "C:\Users\HP\AppData\Roaming\npm\node_modules\npm\bin\npm-cli.js" "install" "node-pre-gyp"
npm ERR! node v4.4.7
npm ERR! npm v3.10.6
npm ERR! path C:\Users\HP\AppData\Roaming\npm\node_modules.staging\sqlite3-246ee2c4
npm ERR! code EBUSY
npm ERR! errno -4082
npm ERR! syscall rmdir

npm ERR! EBUSY: resource busy or locked, rmdir 'C:\Users\HP\AppData\Roaming\npm\node_modules.staging\sqlite3-246ee2c4'
npm ERR!
npm ERR! If you need help, you may report this error at:
npm ERR! https://github.com/npm/npm/issues

npm ERR! Please include the following file with any support request:
npm ERR! C:\Users\HP\AppData\Roaming\npm\node_modules.staging\sqlite3-246ee2c4\npm-debug.log
npm WARN install:[email protected] [email protected] preinstall: npm install node-pre-gyp
npm WARN install:[email protected] Exit status 4294963214

[email protected] preinstall C:\Users\HP\AppData\Roaming\npm\node_modules.staging\strong-arc-13fb10de
node .sl-blip.js

C:\Users\HP\AppData\Roaming\npm
`-- (empty)

npm WARN optional Skipping failed optional dependency /strongloop/modern-syslog:
npm WARN notsup Not compatible with your operating system or architecture: [email protected]
npm WARN optional Skipping failed optional dependency /strongloop/strong-supervisor/modern-syslog:
npm WARN notsup Not compatible with your operating system or architecture: [email protected]
npm ERR! Windows_NT 10.0.10586
npm ERR! argv "C:\Program Files\nodejs\node.exe" "C:\Users\HP\AppData\Roaming\npm\node_modules\npm\bin\npm-cli.js" "install" "-g" "strongloop"
npm ERR! node v4.4.7
npm ERR! npm v3.10.6
npm ERR! file C:\WINDOWS\system32\cmd.exe
npm ERR! path C:\WINDOWS\system32\cmd.exe
npm ERR! code ELIFECYCLE
npm ERR! errno ENOENT
npm ERR! syscall spawn C:\WINDOWS\system32\cmd.exe

npm ERR! [email protected] preinstall: node .sl-blip.js
npm ERR! spawn C:\WINDOWS\system32\cmd.exe ENOENT
npm ERR!
npm ERR! Failed at the [email protected] preinstall script 'node .sl-blip.js'.
npm ERR! Make sure you have the latest version of node.js and npm installed.
npm ERR! If you do, this is most likely a problem with the strong-arc package,
npm ERR! not with npm itself.
npm ERR! Tell the author that this fails on your system:
npm ERR! node .sl-blip.js
npm ERR! You can get information on how to open an issue for this project with:
npm ERR! npm bugs strong-arc
npm ERR! Or if that isn't available, you can get their info via:
npm ERR! npm owner ls strong-arc
npm ERR! There is likely additional logging output above.

npm ERR! Please include the following file with any support request:
npm ERR! G:\Angular-2\Angular-2 firebase\Demoapp2\src\app\npm-debug.log
If applicable.

Nature of the issue

Is this an issue with the layout/behavior/UX of the site or a problem with missing/inaccurate documentation content?
In general, use this (loopback.io) repo for issues with layout/behavior/UX of the site, and other repos for doc content.

Expected behavior

What did you expect to happen?

Actual behavior

What actually happenend, with steps to reproduce (if applicable).

Suggested resolution

How do you think this should be resolved (optional).

This is the series of events that has to happen to switch from http://docs.strongloop.com to http://loopback.io/doc:

• Review and test all migrated English content.
• Fix all broken links per #44
• Fix search feature per #31.
• Incorporate README content from example repos, etc. per #30.
• Import translated docs from Confluence per #37.
• Fix tags per #41 (not required, but "nice to have")
• Set up Google Analytics per #45.
• Copy LB 2.x content into LB3 directory and make other initial changes in 3.0 docs.
• Add link in header nav bar on loopback.io to http://loopback.io/doc.
• Publish blog post announcing new doc site, deprecating old site, explaining how to contribute, etc.
• Add redirects on docs.strongloop.com to corresponding pages in http://loopback.io/doc and deprecation notices everywhere else.
• Update links to docs on strongloop.com (Dave W), https://developer.ibm.com/open/, KC docs, and anywhere else.

Add Meteor to http://loopback.io/resources/#compare

https://www.meteor.com/

@bajtos suggested:

Should we eventually move LoopBack's portion of apidocs.strongloop.com to apidocs.loopback.io?

This would just be a DNS change, approved in principle by @ritch and @raymondfeng.
However, it would be strange to have non-LoopBack docs on loopback.io, so we'd want to review the status of the API docs for:

• strong-cluster-connect-store
• strong-cluster-control
• strong-cluster-tls-store
• strong-mq
• strong-store-cluster
• strong-task-emitter

(see http://apidocs.strongloop.com/ for the content).

Can we eliminate the API docs and rely on the GitHub READMEs for the above? @sam-github

For example, http://loopback.io/doc/en/contrib/tag_getting_started.html

Found on the following page: http://loopback.io/doc/en/contrib/index.html

yo loopback

Error: Cannot find module 'ansi-styles'
at Function.Module._resolveFilename (module.js:338:15)
at Function.Module._load (module.js:280:25)
at Module.require (module.js:364:17)
at require (module.js:380:17)
at Object. (/usr/local/lib/node_modules/generator-loopback/node_modules/yeoman-generator/node_modules/chalk/index.js:2:12)
at Module._compile (module.js:456:26)
at Object.Module._extensions..js (module.js:474:10)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:3

We need to run a comprehensive link-check on the site to identify broken links.

This is on the live site http://loopback.io/doc/en/lb2/
@ritch

URL of the page

FA owners doc page.

Nature of the issue

layout

Expected behavior

just look like a table for easy reading

Actual behavior

a tree list ATM

Suggested resolution

Refactor

Add redirects on docs.strongloop.com to corresponding pages in http://loopback.io/doc and deprecation notices everywhere else. Need to cover:

• LB space
• APIC space

Also look for any links to pages in those spaces in remaining docs.strongloop.com pages.

We've migrated all the LoopBack content from docs.strongloop.com, but there are some pages that didn't get moved that are not part of LoopBack per se, but are related.

Should we move any or all of these?

• Building a real-time app using socket.io and AngularJS
• Pub-sub - (NOTE loopback-example-pubsub is alerady in _includes/readmes)
• Supporting module reference

Currently, links to other doc. pages are constructed as follows (for example):

[PersistedModel REST API](/doc/{{page.lang}}/lb2/PersistedModel-REST-API.html)

The original intent was to ensure that links go to the appropriate translation, but it is problematic for include templates (where the liquid variable {{page.lang}} is not allowed in a template parameter.

Also, when we duplicate the docs for the LB 3.0 release, we'll have to go through and replace lb2 everywhere with lb3

However, due to the way we've set up the pages sub-folders, we could just link to the page name, e.g.

[PersistedModel REST API](PersistedModel-REST-API.html)

This will work for all languages and would not require any changes for LB3 (or other subsequent) releases.

Nature of the issue

Currently, for non-English spaces, untranslated articles simply return a 404 Not Found. For example: http://loopback.io/doc/fr/lb2/Creating-an-application.html.

Expected behavior

I would like the page to display a message saying that it hasn't yet been translated, and provide a link to the corresponding English page.

Actual behavior

Currently displays "Page Not Found"

Suggested resolution

See prototype in https://github.com/crandmck/loopback.io (for ja docs only).

The original implementation of the sidebar didn't allow sidebar container items to be linked to a topic. You can see the default implementation in http://idratherbewriting.com/documentation-theme-jekyll/: The sidebar container items "Overview", "Release Notes", "Installation", etc. are only containers, they are not pages themselves.

But since our topic hierarchy was laid out such that containers were also themselves topics, I changed the _includes/sidebar.html template to allow for that. However, the problem now is that when you click on a container topic, it doesn't "expand" the child topics; you have to click the inverted triangle to do that. While this works, it's inconvenient and could be confusing.

I'd like the child topics to be displayed by default. So, for example, when you click on LoopBack core concepts, I'd like it to expand the child topics underneath ("Routing", "LoopBack FAQ", etc) as well as display the "LoopBack core concepts" page.

URL of the page : http://loopback.io/doc/en/lb2/Use-API-Explorer.html

Nature of the issue: 'git checkout step1' not working

Expected behavior

Executing 'git checkout step1' should work

Actual behavior

Get following error:
"error: pathspec 'step1' did not match any file(s) known to git."

Suggested resolution

This should work as expected instead of giving an error

The Jekyll template has provision for this. We just have to set the GA ID in _config.yml via google_analytics

I created two new layouts that work fine when I run Jekyll locally, but not on the site:

• Readme layout - here is the layout file
• Navgroup layout - here is the layout file

URL of the page

For example: http://loopback.io/doc/en/lb2/Managing-users.html

What it should look like (from running Jekyll locally):

Notice that the "see also" box floats to the right of the TOC, which looks better.

Also:

http://loopback.io/doc/en/lb2/Connecting-to-MySQL.html

What it should look like (from running Jekyll locally):

The "Note" is displayed at the top of the page above the TOC, which looks better.

Nature of the issue

All the files in the repo seem to be up to date. It's a matter of the actual HTML not laying out in the order that it should be. I'm stumped.

@Sequoia I know you're busy with other stuff, but if you have a moment, I would appreciate your eyes. LMK if you have questions, as it's somewhat complicated... or anyone else with Jekyll experience @eddiemonge :-)

URL of the page

Add info from internal KB on CI/branching to http://loopback.io/doc/en/contrib/code-contrib.html
Not sure if it should be a section in this page or a "child" page.

Nature of the issue

Per https://github.com/strongloop-internal/loopback-knowledge-base/pull/105, the information in the CI branch rules page is useful to community contributors too, as it describes the reasons behind our decision to use latest in dev-dependencies.

Include info on project level things we decide that should be publicized, eg:

• How we use CI
• Why we have N branches in all repos
• Which branches are protected, etc

Suggested resolution

Just need to merge info from the internal KB page into loopback.io.

cc @bajtos @superkhau

This involves not only duplicating the content, but also getting all the images over. See Migrating LoopBack Docs to Markdown for use with Jekyll.

This is part of Proposal to make LoopBack documentation open source.

Currently, the sidebar nav only allows three levels of hierarchy:

• Top-level "folders"
  • Second-level "subfolders"
    • Third-level "subfolder items"

This works for most of our content, but there are a few areas where we could use one more level. The code that processes the yml sidebar file does not currently support this.

In addition, there is an oddity left over from the original implementation where the first item in a "folder" cannot be a "subfolder" (only a non-container leaf node is allowed). For example, I had to stick a dummy item http://loopback.io/doc/en/lb2/Defining-models.html under the container, because the first item, Creating models, is a "subfolder". Without the intervening item, jekyll gives a build error:

           Error: (/Users/rand/StrongLoop/loopback.io/_data/sidebars/lb2_sidebar.yml): did not find expected key while parsing a block mapping at line 236 column 5

I would like to be able to make an article be a "container" in the sidebar, regardless of where it occurs.