Skip to content

Commit cbfc739

Browse files
ThibautThibaut
committed
Improve Help page
Closes freeCodeCamp#676.
1 parent 6c80c22 commit cbfc739

4 files changed

Lines changed: 66 additions & 23 deletions

File tree

‎assets/javascripts/templates/pages/help_tmpl.coffee‎

Lines changed: 50 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,68 @@
1-
ctrlKey = if $.isMac() then 'cmd' else 'ctrl'
2-
navKey = if $.isMac() then 'cmd' else 'alt'
1+
app.templates.helpPage = ->
2+
ctrlKey = if $.isMac() then 'cmd' else 'ctrl'
3+
navKey = if $.isMac() then 'cmd' else 'alt'
34

4-
app.templates.helpPage = """
5+
aliases_one = {}
6+
aliases_two = {}
7+
keys = Object.keys(app.models.Entry.ALIASES)
8+
middle = Math.ceil(keys.length / 2) - 1
9+
for key, i in keys
10+
(if i > middle then aliases_two else aliases_one)[key] = app.models.Entry.ALIASES[key]
11+
12+
"""
513
<nav class="_toc" role="directory">
614
<h3 class="_toc-title">Table of Contents</h3>
715
<ul class="_toc-list">
16+
<li><a href="#managing-documentations">Managing Documentations</a>
817
<li><a href="#search">Search</a>
918
<li><a href="#shortcuts">Keyboard Shortcuts</a>
1019
<li><a href="#aliases">Search Aliases</a>
1120
</ul>
1221
</nav>
1322
14-
<h1 class="_lined-heading">Help</h2>
23+
<h1 class="_lined-heading">User Guide</h2>
24+
25+
<h2 class="_block-heading" id="managing-documentations">Managing Documentations</h2>
26+
<p>
27+
Documentations can be enabled and disabled in the <a href="/settings">Preferences</a>.
28+
Alternatively, you can enable a documentation by searching for it in the main search
29+
and clicking the "Enable" link in the results.
30+
For faster and better search, only enable the documentations you plan on actively using.
31+
<p>
32+
Once a documentation is enabled, it becomes part of the search and its content can be downloaded for offline access — and faster page loads when online — in the <a href="/offline">Offline</a> area.
1533
1634
<h2 class="_block-heading" id="search">Search</h2>
1735
<p>
18-
The search is case-insensitive. It supports fuzzy matching
36+
The search is case-insensitive and ignores whitespace. It supports fuzzy matching
1937
(e.g. <code class="_label">bgcp</code> matches <code class="_label">background-clip</code>)
20-
and aliases (<a href="#aliases">full list</a> below).
38+
as well as aliases (full list <a href="#aliases">below</a>).
2139
<dl>
2240
<dt id="doc_search">Searching a single documentation
2341
<dd>
24-
You can scope the search to a single documentation by typing its name (or an abbreviation)
25-
and pressing <code class="_label">Tab</code> (<code class="_label">Space</code> on mobile devices).
42+
The search can be scoped to a single documentation by typing its name (or an abbreviation)
43+
and pressing <code class="_label">tab</code> (<code class="_label">space</code>&nbsp;on mobile).
2644
For example, to search the JavaScript documentation, enter <code class="_label">javascript</code>
27-
or <code class="_label">js</code>, then <code class="_label">Tab</code>.<br>
28-
To clear the current scope, empty the search field and hit <code class="_label">Backspace</code>.
45+
or <code class="_label">js</code>, then <code class="_label">tab</code>.<br>
46+
To clear the current scope, empty the search field and hit <code class="_label">backspace</code> or
47+
<code class="_label">esc</code>.
2948
<dt id="url_search">Prefilling the search field
3049
<dd>
31-
The search field can be prefilled from the URL by visiting <a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23q%3Dkeyword" target="_top">devdocs.io/#q=keyword</a>.
50+
The search can be prefilled from the URL by visiting <a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23q%3Dkeyword" target="_top">devdocs.io/#q=keyword</a>.
3251
Characters after <code class="_label">#q=</code> will be used as search query.<br>
33-
To search a single documentation, add its name and a space before the keyword:
52+
To search a single documentation, add its name (or an abbreviation) and a space before the keyword:
3453
<a href="/#q=js%20date" target="_top">devdocs.io/#q=js date</a>.
3554
<dt id="browser_search">Searching using the address bar
3655
<dd>
3756
DevDocs supports OpenSearch. It can easily be installed as a search engine on most web browsers:
3857
<ul>
39-
<li>On Chrome, the setup is done automatically. Simply press <code class="_label">Tab</code> when devdocs.io is autocompleted
58+
<li>On Chrome, the setup is done automatically. Simply press <code class="_label">tab</code> when devdocs.io is autocompleted
4059
in the omnibox (to set a custom keyword, click <em>Manage search engines\u2026</em> in Chrome's settings).
4160
<li>On Firefox, open the search engine list (icon in the search bar) and click <em>Add "DevDocs Search"</em>.
4261
DevDocs is now available in the search bar. You can also search from the location bar by following
4362
<a href="https://support.mozilla.org/en-US/kb/how-search-from-address-bar">these instructions</a>.
4463
</dl>
64+
<p>
65+
<i>Note: the above search features only work for documentations that are enabled.</i>
4566
4667
<h2 class="_block-heading" id="shortcuts">Keyboard Shortcuts</h2>
4768
<h3 class="_shortcuts-title">Sidebar</h3>
@@ -95,8 +116,8 @@ app.templates.helpPage = """
95116
<code class="_shortcut-code">ctrl + ,</code>
96117
<dd class="_shortcuts-dd">Open preferences
97118
<dt class="_shortcuts-dt">
98-
<code class="_shortcut-code">escape</code>
99-
<dd class="_shortcuts-dd">Reset UI
119+
<code class="_shortcut-code">esc</code>
120+
<dd class="_shortcuts-dd">Clear search field / reset UI
100121
<dt class="_shortcuts-dt">
101122
<code class="_shortcut-code">?</code>
102123
<dd class="_shortcuts-dd">Show this page
@@ -118,11 +139,19 @@ app.templates.helpPage = """
118139
continue to type and it will refocus the search field and start showing new results.
119140
120141
<h2 class="_block-heading" id="aliases">Search Aliases</h2>
121-
<table>
122-
<tr>
123-
<th>Word
124-
<th>Alias
125-
#{("<tr><td class=\"_code\">#{key}<td class=\"_code\">#{value}" for key, value of app.models.Entry.ALIASES).join('')}
126-
</table>
142+
<div class="_aliases">
143+
<table>
144+
<tr>
145+
<th>Word
146+
<th>Alias
147+
#{("<tr><td class=\"_code\">#{key}<td class=\"_code\">#{value}" for key, value of aliases_one).join('')}
148+
</table>
149+
<table>
150+
<tr>
151+
<th>Word
152+
<th>Alias
153+
#{("<tr><td class=\"_code\">#{key}<td class=\"_code\">#{value}" for key, value of aliases_two).join('')}
154+
</table>
155+
</div>
127156
<p>Feel free to suggest new aliases on <a href="https://github.com/Thibaut/devdocs/issues/new">GitHub</a>.
128157
"""

‎assets/javascripts/views/content/static_page.coffee‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ class app.views.StaticPage extends app.View
44
@titles:
55
about: 'About'
66
news: 'News'
7-
help: 'Help'
7+
help: 'User Guide'
88
notFound: '404'
99

1010
deactivate: ->

‎assets/stylesheets/components/_content.scss‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -354,6 +354,20 @@
354354
@extend %label;
355355
}
356356

357+
//
358+
// Search aliases
359+
//
360+
361+
._aliases {
362+
display: flex;
363+
justify-content: space-between;
364+
365+
> table {
366+
margin-top: 0;
367+
width: calc(50% - 0.5rem);
368+
}
369+
}
370+
357371
//
358372
// Utilities
359373
//

‎views/app.erb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@
2323
<a href="/settings" class="_menu-link">Preferences</a>
2424
<a href="/offline" class="_menu-link">Offline Data</a>
2525
<a href="/news" class="_menu-link">Changelog</a>
26-
<a href="/help" class="_menu-link">Help</a>
26+
<a href="/help" class="_menu-link">Guide</a>
2727
<a href="/about" class="_menu-link">About</a>
2828
</nav>
2929
</header>

0 commit comments

Comments
 (0)