From 88f6965e772012c29faa620c3972773ff173f18d Mon Sep 17 00:00:00 2001 From: Dmitry Blotsky Date: Thu, 4 Feb 2016 22:36:42 -0800 Subject: [PATCH] CB-10449 CB-10417 Moving anchor creation out of ToC logic. Moving ID creation into JS because RedCarpet doesn't support Unicode headings. Removing old '#link-' links. Making permalink icons a bit smaller and making them always show on small and medium screens. --- _config.yml | 6 +- .../guide/platforms/amazonfireos/config.md | 5 +- www/docs/en/dev/cordova/events/events.md | 30 ++++----- www/docs/en/dev/guide/cli/index.md | 4 +- www/docs/en/dev/guide/next/index.md | 2 +- .../en/dev/guide/platforms/android/config.md | 2 +- .../en/dev/guide/platforms/android/plugin.md | 4 +- www/docs/en/dev/guide/platforms/ios/plugin.md | 4 +- www/docs/en/dev/guide/platforms/wp8/plugin.md | 6 +- www/index.html | 2 +- www/plugins/faq.md | 2 +- www/static/css-src/_docs.scss | 23 ++++--- www/static/css-src/main.scss | 3 +- www/static/js/docs.js | 67 ++++++++++++++----- 14 files changed, 98 insertions(+), 62 deletions(-) diff --git a/_config.yml b/_config.yml index 1923575bec..0e2c49fc86 100644 --- a/_config.yml +++ b/_config.yml @@ -66,11 +66,11 @@ redcarpet: # not have a leading or trailing newline - lax_spacing + # allows tables - tables - - highlight - # enables anchor links - - with_toc_data + # surrounds highlighted text with s + - highlight kramdown: input: GFM diff --git a/www/docs/en/5.0.0/guide/platforms/amazonfireos/config.md b/www/docs/en/5.0.0/guide/platforms/amazonfireos/config.md index 8a99227bc2..ab219cbbb4 100644 --- a/www/docs/en/5.0.0/guide/platforms/amazonfireos/config.md +++ b/www/docs/en/5.0.0/guide/platforms/amazonfireos/config.md @@ -46,7 +46,7 @@ File](config_ref_index.md.html#The%20config.xml%20File) for information on globa page of an application. The title and message are separated by a comma in this value string, and that comma is removed before the dialog is displayed. - + - `LoadingPageDialog` (string, defaults to `null`): The same as `LoadingDialog`, @@ -70,7 +70,7 @@ File](config_ref_index.md.html#The%20config.xml%20File) for information on globa time the splash screen image displays. - + - `ShowTitle` (boolean, defaults to `false`): Show the title at the top of the screen. @@ -81,4 +81,3 @@ File](config_ref_index.md.html#The%20config.xml%20File) for information on globa values are `ERROR`, `WARN`, `INFO`, `DEBUG`, and `VERBOSE`. - diff --git a/www/docs/en/dev/cordova/events/events.md b/www/docs/en/dev/cordova/events/events.md index bb5c6ead56..69d6dea701 100644 --- a/www/docs/en/dev/cordova/events/events.md +++ b/www/docs/en/dev/cordova/events/events.md @@ -71,9 +71,7 @@ The application code could add listeners for these events. For example: // Add similar event handlers for other events -**Note**: Applications typically should use `document.addEventListener` to -attach an event listener once the [deviceready](#link-deviceready) -event fires. +**Note**: Applications typically should use `document.addEventListener` to attach an event listener once the [deviceready](#deviceready) The following table lists the cordova events and the supported platforms: @@ -92,9 +90,9 @@ The following table lists the cordova events and the supported platforms: - + - deviceready + deviceready @@ -103,7 +101,7 @@ The following table lists the cordova events and the supported platforms: - pause + pause @@ -112,7 +110,7 @@ The following table lists the cordova events and the supported platforms: - resume + resume @@ -121,7 +119,7 @@ The following table lists the cordova events and the supported platforms: - backbutton + backbutton @@ -130,7 +128,7 @@ The following table lists the cordova events and the supported platforms: - menubutton + menubutton @@ -139,7 +137,7 @@ The following table lists the cordova events and the supported platforms: - searchbutton + searchbutton @@ -148,7 +146,7 @@ The following table lists the cordova events and the supported platforms: - startcallbutton + startcallbutton @@ -157,7 +155,7 @@ The following table lists the cordova events and the supported platforms: - endcallbutton + endcallbutton @@ -166,7 +164,7 @@ The following table lists the cordova events and the supported platforms: - volumedownbutton + volumedownbutton @@ -175,13 +173,13 @@ The following table lists the cordova events and the supported platforms: - volumeupbutton + volumeupbutton - + @@ -261,7 +259,7 @@ The `resume` event fires when the native platform pulls the application out from ### iOS Quirks -Any interactive functions called from a [pause](#link-pause) event handler execute +Any interactive functions called from a [pause](#pause) event handler execute later when the app resumes, as signaled by the `resume` event. These include alerts, `console.log()`, and any calls from plugins or the Cordova API, which go through Objective-C. diff --git a/www/docs/en/dev/guide/cli/index.md b/www/docs/en/dev/guide/cli/index.md index c2f7031658..0f2a8a6da6 100644 --- a/www/docs/en/dev/guide/cli/index.md +++ b/www/docs/en/dev/guide/cli/index.md @@ -558,5 +558,5 @@ you're building: $ cordova platform update ios ...etc. -[DeviceReadyEvent]: ../../cordova/events/events.html#link-deviceready -[BackButtonEvent]: ../../cordova/events/events.html#link-backbutton +[DeviceReadyEvent]: ../../cordova/events/events.html#deviceready +[BackButtonEvent]: ../../cordova/events/events.html#backbutton diff --git a/www/docs/en/dev/guide/next/index.md b/www/docs/en/dev/guide/next/index.md index 8a987edf88..7da3ec7d9c 100644 --- a/www/docs/en/dev/guide/next/index.md +++ b/www/docs/en/dev/guide/next/index.md @@ -216,4 +216,4 @@ This Google Group was the old support forum when Cordova was still called PhoneG Consider finding a local Cordova/PhoneGap meetup group -[DeviceReadyEvent]: ../../cordova/events/events.html#link-deviceready +[DeviceReadyEvent]: ../../cordova/events/events.html#deviceready diff --git a/www/docs/en/dev/guide/platforms/android/config.md b/www/docs/en/dev/guide/platforms/android/config.md index 4dc09b5cec..61e3aa3ba1 100644 --- a/www/docs/en/dev/guide/platforms/android/config.md +++ b/www/docs/en/dev/guide/platforms/android/config.md @@ -123,4 +123,4 @@ File](config_ref_index.md.html#The%20config.xml%20File) for information on globa -[PauseEvent]: ../../../cordova/events/events.html#link-pause +[PauseEvent]: ../../../cordova/events/events.html#pause diff --git a/www/docs/en/dev/guide/platforms/android/plugin.md b/www/docs/en/dev/guide/platforms/android/plugin.md index 1faf9262c4..d8036027a6 100644 --- a/www/docs/en/dev/guide/platforms/android/plugin.md +++ b/www/docs/en/dev/guide/platforms/android/plugin.md @@ -463,5 +463,5 @@ on your device or emulator to simulate low memory scenarios. If your plugin launches external activities, you should always do some testing with this setting enabled to ensure that you are properly handling low memory scenarios. -[PauseEvent]: ../../../cordova/events/events.html#link-pause -[ResumeEvent]: ../../../cordova/events/events.html#link-resume +[PauseEvent]: ../../../cordova/events/events.html#pause +[ResumeEvent]: ../../../cordova/events/events.html#resume diff --git a/www/docs/en/dev/guide/platforms/ios/plugin.md b/www/docs/en/dev/guide/platforms/ios/plugin.md index 58d6b7c148..7648ab946d 100644 --- a/www/docs/en/dev/guide/platforms/ios/plugin.md +++ b/www/docs/en/dev/guide/platforms/ios/plugin.md @@ -249,5 +249,5 @@ can attach Safari 8.0 to the app running within the iOS 8 Simulator. [CDVCommandDelegate.h]: https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/Public/CDVCommandDelegate.h [CDVPlugin.h]: https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/Public/CDVPlugin.h [CDVPlugin.m]: https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/Public/CDVPlugin.m -[ResumeEvent]: ../../../cordova/events/events.html#link-resume -[PauseEvent]: ../../../cordova/events/events.html#link-pause +[ResumeEvent]: ../../../cordova/events/events.html#resume +[PauseEvent]: ../../../cordova/events/events.html#pause diff --git a/www/docs/en/dev/guide/platforms/wp8/plugin.md b/www/docs/en/dev/guide/platforms/wp8/plugin.md index d7ab55900a..dae70e5ab5 100644 --- a/www/docs/en/dev/guide/platforms/wp8/plugin.md +++ b/www/docs/en/dev/guide/platforms/wp8/plugin.md @@ -23,7 +23,7 @@ title: Windows Phone 8 Plugins # Windows Phone 8 Plugins This section provides details for how to implement native plugin code -on the Windows Phone platform. Before reading this, see [Plugin Development Guide](../../hybrid/plugins/index.html) +on the Windows Phone platform. Before reading this, see [Plugin Development Guide](../../hybrid/plugins/index.html) for an overview of the plugin's structure and its common JavaScript interface. This section continues to demonstrate the sample _echo_ plugin that communicates from the Cordova webview to the native @@ -237,5 +237,5 @@ yourself of errors. unnecessary functionality from the plugin's various native implementations. -[PauseEvent]: ../../../cordova/events/events.html#link-pause -[ResumeEvent]: ../../../cordova/events/events.html#link-resume +[PauseEvent]: ../../../cordova/events/events.html#pause +[ResumeEvent]: ../../../cordova/events/events.html#resume diff --git a/www/index.html b/www/index.html index e99bd9b630..2fd6155d62 100644 --- a/www/index.html +++ b/www/index.html @@ -157,7 +157,7 @@

Common next steps

Read the docs
  • - Add a Plugin + Add a Plugin
  • Add Icons and Splash Screen diff --git a/www/plugins/faq.md b/www/plugins/faq.md index 2f0594c1ad..c977635bb4 100644 --- a/www/plugins/faq.md +++ b/www/plugins/faq.md @@ -38,7 +38,7 @@ See Cordova [blog]({{ site.baseurl }}/announcements/2015/04/21/plugins-release-a ## Are there any additional documents to assist me with plugins? -Yes there are. Please take a look at [Add Plugin Features]({{ site.baseurl }}/docs/en/{{ site.default_linked_docs_version }}/guide/cli/#link-add-plugin-features) for a more detailed guide. +Yes there are. Please take a look at [Add Plugin Features]({{ site.baseurl }}/docs/en/{{ site.default_linked_docs_version }}/guide/cli/#add-plugin-features) for a more detailed guide. ## I don't like X. How can I help improve the website? diff --git a/www/static/css-src/_docs.scss b/www/static/css-src/_docs.scss index bea37fe546..232e4ccc85 100644 --- a/www/static/css-src/_docs.scss +++ b/www/static/css-src/_docs.scss @@ -21,13 +21,14 @@ * Anchor links on documentation headers */ .header-link { - position: relative; - left: 0.5em; - opacity: 0; - - -webkit-transition: opacity 0.2s ease-in-out 0.1s; - -moz-transition: opacity 0.2s ease-in-out 0.1s; - -ms-transition: opacity 0.2s ease-in-out 0.1s; + position: relative; + left: 0.5em; + opacity: 0; + font-size: 0.7em; + + -webkit-transition: opacity 0.2s ease-in-out 0.1s; + -moz-transition: opacity 0.2s ease-in-out 0.1s; + -ms-transition: opacity 0.2s ease-in-out 0.1s; } h2:hover .header-link, @@ -35,7 +36,7 @@ h4:hover .header-link, h5:hover .header-link, h6:hover .header-link { - opacity: 1; + opacity: 1; } pre { @@ -264,6 +265,12 @@ } } +@media (max-width: $screen-sm-max) { + .header-link { + opacity: 1 !important; + } +} + // Workaround for the spacing on the Russian /docs/ru/version/index.html pages html[lang="ru"] .docs #home ul li { height: 160px; diff --git a/www/static/css-src/main.scss b/www/static/css-src/main.scss index d0f718aa5d..c174155501 100644 --- a/www/static/css-src/main.scss +++ b/www/static/css-src/main.scss @@ -40,8 +40,7 @@ $screen-xs-max: $screen-sm-min - 1; $screen-md-min: 992px; $screen-sm-max: $screen-md-min - 1; $screen-lg-min: 1200px; -$screen-lg: (min-width: $screen-lg-min); -$screen-md-max: $screen-lg - 1; +$screen-md-max: $screen-lg-min - 1; /* Mixin that prefixes any CSS rule */ diff --git a/www/static/js/docs.js b/www/static/js/docs.js index d3a5cbf885..efb2d93f8f 100644 --- a/www/static/js/docs.js +++ b/www/static/js/docs.js @@ -17,49 +17,82 @@ $(document).ready(function () { - function getAnchorName(i, heading, prefix) { - var name = prefix; + function slugify(text) { + text = text.toLowerCase(); + + // replace unaccepted characters with spaces + // NOTE: + // a better regex would have been /[^\d\s\w]/ug, but the 'u' flag + // (Unicode) is not supported in some browsers, and we support + // many languages that use Unicode characters + text = text.replace(/[\[\]\(\)\=\+\?]/g, ' '); + + // trim whitespace and replace runs of whitespace with single dashes + text = text.trim().replace(/ +/g, '-'); + + return text; + } + + function getIdForHeading(heading) { if (heading.id) { - name += heading.id; + return heading.id; } else if (heading.name) { - name += heading.name; + return heading.name; } else { - name += i; + return slugify(heading.innerText); } - return name; } - var anchorLink = function (id) { - var anchor = document.createElement("a"); + function permalinkTo(id) { + var anchor = document.createElement("a"); anchor.className = "header-link"; anchor.href = "#" + id; anchor.innerHTML = ""; return anchor; } + function anchorFor(id) { + var anchor = document.createElement("a"); + anchor.className = "fragment-anchor"; + anchor.id = id; + return anchor; + } + + // go through all headings in the content and add some links + $('#page-toc-source h1, #page-toc-source h2, #page-toc-source h3, #page-toc-source h4, #page-toc-source h5, #page-toc-source h6') + .each(function (i, heading) { + + headingId = getIdForHeading(heading); + + // add an anchor for linking to the heading + // NOTE: + // we could have set the ID on the heading itself but we didn't + // because the has some extra CSS that floats it above the + // heading and makes it easier to see when linked + $(heading).before(anchorFor(headingId)) + + // add a permalink to all but the first heading + if (i > 0) { + $(heading).append(permalinkTo(headingId)); + } + }); + // Table of Contents $('#page-toc').toc({ 'selectors': 'h1,h2', // elements to use as headings 'container': '#page-toc-source', // element to find all selectors in - 'prefix': 'link-', // prefix for anchor tags and class names + 'prefix': '', // prefix for anchor tags and class names 'onHighlight': function(el) {}, // called when a new section is highlighted 'highlightOnScroll': true, // add class to heading that is currently in focus 'highlightOffset': 100, // offset to trigger the next headline 'anchorName': function(i, heading, prefix) { // custom function for anchor name - return getAnchorName(i, heading, prefix); + return getIdForHeading(heading); }, 'headerText': function(i, heading, $heading) { // custom function building the header-item text return $heading.text(); }, 'itemClass': function(i, heading, $heading, prefix) { // custom function for item class - // the first link is the H1 header of the page - exclude it - if (i > 0) { - // add a special class to the anchor for this toc entry - var anchorName = getAnchorName(i, heading, prefix); - $('#' + anchorName).addClass('fragment-anchor'); - $heading.append(anchorLink(anchorName)); - } // don't assign any special classes to the toc entry itself return ''; }