You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cordova.apache.org by dblotsky <gi...@git.apache.org> on 2016/02/05 07:41:58 UTC
[GitHub] cordova-docs pull request: Doc Anchor Fixes
GitHub user dblotsky opened a pull request:
https://github.com/apache/cordova-docs/pull/487
Doc Anchor Fixes
- Moving anchor creation out of ToC logic.
- Moving ID creation into JS because RedCarpet doesn't support Unicode headings.
- Making permalink icons a bit smaller and making them always show on small and medium screens.
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/MSOpenTech/cordova-docs doc-anchors
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/cordova-docs/pull/487.patch
To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:
This closes #487
----
commit a27e14158818c96bb6140fd5d960a5edd9123267
Author: Dmitry Blotsky <dm...@gmail.com>
Date: 2016-02-05T06:36:42Z
CB-10449 CB-10417 Moving anchor creation out of ToC logic. Moving ID creation into JS because RedCarpet doesn't support Unicode headings. Making permalink icons a bit smaller and making them always show on small and medium screens.
----
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-docs pull request: Doc Anchor Fixes
Posted by dblotsky <gi...@git.apache.org>.
Github user dblotsky commented on a diff in the pull request:
https://github.com/apache/cordova-docs/pull/487#discussion_r52270478
--- Diff: www/static/js/docs.js ---
@@ -17,49 +17,81 @@
$(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 = "<i class=\"glyphicon glyphicon-link\"></i>";
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').each(function (i, heading) {
--- End diff --
Added H3.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-docs pull request: Doc Anchor Fixes
Posted by dblotsky <gi...@git.apache.org>.
Github user dblotsky commented on the pull request:
https://github.com/apache/cordova-docs/pull/487#issuecomment-180224660
@nikhilkh @riknoll @sarangan12 Please review when you folks get a chance.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-docs pull request: Doc Anchor Fixes
Posted by nikhilkh <gi...@git.apache.org>.
Github user nikhilkh commented on a diff in the pull request:
https://github.com/apache/cordova-docs/pull/487#discussion_r52092001
--- Diff: www/static/js/docs.js ---
@@ -17,49 +17,81 @@
$(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 = "<i class=\"glyphicon glyphicon-link\"></i>";
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').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 <a> 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': 'toc-', // prefix for anchor tags and class names
--- End diff --
can we remove the prefix?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-docs pull request: Doc Anchor Fixes
Posted by dblotsky <gi...@git.apache.org>.
Github user dblotsky commented on the pull request:
https://github.com/apache/cordova-docs/pull/487#issuecomment-181723090
@nikhilkh: good catch! Fixed links with `#link-` in them.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-docs pull request: Doc Anchor Fixes
Posted by asfgit <gi...@git.apache.org>.
Github user asfgit closed the pull request at:
https://github.com/apache/cordova-docs/pull/487
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-docs pull request: Doc Anchor Fixes
Posted by dblotsky <gi...@git.apache.org>.
Github user dblotsky commented on a diff in the pull request:
https://github.com/apache/cordova-docs/pull/487#discussion_r52270223
--- Diff: www/static/js/docs.js ---
@@ -17,49 +17,81 @@
$(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 = "<i class=\"glyphicon glyphicon-link\"></i>";
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').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 <a> 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': 'toc-', // prefix for anchor tags and class names
--- End diff --
Yep, I removed it from the code. I'll make it empty to make that more clear.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-docs pull request: Doc Anchor Fixes
Posted by riknoll <gi...@git.apache.org>.
Github user riknoll commented on a diff in the pull request:
https://github.com/apache/cordova-docs/pull/487#discussion_r52092095
--- Diff: www/static/js/docs.js ---
@@ -17,49 +17,81 @@
$(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 = "<i class=\"glyphicon glyphicon-link\"></i>";
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').each(function (i, heading) {
--- End diff --
+1 The Android guide definitely requires referencing H3+
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-docs pull request: Doc Anchor Fixes
Posted by dblotsky <gi...@git.apache.org>.
Github user dblotsky commented on the pull request:
https://github.com/apache/cordova-docs/pull/487#issuecomment-181723638
@nikhilkh I kept `#page-toc-source` because it's just an ID, which just happens to be used by the ToC too. If the ID ever changes or is moved, all uses of it should be examined and then we can create another one if required. The motivation to not touch it unless necessary is the fact that changing it will lead to a massive SVN commit (and right now it's not strictly necessary).
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-docs pull request: Doc Anchor Fixes
Posted by nikhilkh <gi...@git.apache.org>.
Github user nikhilkh commented on a diff in the pull request:
https://github.com/apache/cordova-docs/pull/487#discussion_r52091918
--- Diff: www/static/js/docs.js ---
@@ -17,49 +17,81 @@
$(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 = "<i class=\"glyphicon glyphicon-link\"></i>";
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').each(function (i, heading) {
--- End diff --
Does this still couple it to the TOC - `#page-toc-source`? Also, we should add links for all headings h3+ should be included.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-docs pull request: Doc Anchor Fixes
Posted by nikhilkh <gi...@git.apache.org>.
Github user nikhilkh commented on the pull request:
https://github.com/apache/cordova-docs/pull/487#issuecomment-182023849
LGTM. Thanks, Dmitry for fixing this! I just tested it and it works very well!
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org
[GitHub] cordova-docs pull request: Doc Anchor Fixes
Posted by nikhilkh <gi...@git.apache.org>.
Github user nikhilkh commented on the pull request:
https://github.com/apache/cordova-docs/pull/487#issuecomment-180636960
I'm assuming you grep'd for any `#link-` anchor links on our site that need to be changed now as we change the slugify scheme and prefix.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org