The sidebar navigation uses a jQuery component called Navgoco. The sidebar is a somewhat complex part of the theme that remembers your current page, highlights the active item, stays in a fixed position on the page, and more. This page explains a bit about how the sidebar was put together.
The sidebar uses the Navgoco jQuery plugin as its basis. Why not use Bootstrap? Navgoco provides a few features that I couldn’t find in Bootstrap:
- Navgoco sets a cookie to remember the user’s position in the sidebar. If you refresh the page, the cookie allows the plugin to remember the state.
- Navgoco inserts an
active
class based on the navigation option that’s open. This is essential for keeping the accordion open.
- Navgoco includes the expand and collapse features of a sidebar.
In short, the sidebar has some complex logic here. I’ve integrated Navgoco’s features with the sidebar.html and sidebar data files to build the sidebar. It’s probably the most impressive part of this theme. (Other themes usually aren’t focused on creating hierarchies of pages, but this kind of hierarchy is important in a documentation site.)
The sidebar.html file (inside the _includes folder) contains the .navgoco
method called on the #mysidebar
element.
There are some options to set within the .navgoco
method. The only noteworthy option is accordion
. This option makes it so when you expand a section, the other sections collapse. It’s a way of keeping your navigation controls condensed.
The value for accordion
is a Boolean (true
or false
). By default, the accordion
option is set as true
. If you don’t want the accordion, set it to false
. Note that there’s also a block of code near the bottom of sidebar.html that is commented out. Uncomment out that section to have the Collapse all and Expand All buttons appear.
There’s a danger with setting the accordion to false
. If you click Expand All and the sidebar expands beyond the dimensions of the browser, users will be stuck. When that happens, it’s hard to collapse it. As a best practice, leave the sidebar’s accordion option set to true
.
The sidebar has one other feature — this one from Bootstrap. If the user’s viewport is tall enough, the sidebar remains fixed on the page. This allows the user to scroll down the page and still keep the sidebar in view.
In the customsscripts.js file in the js folder, there’s a function that adds an affix
class if the height of the browser window is greater than 800 pixels. If the browser’s height is less than 800 pixels, the nav affix
class does not get inserted. As a result, the sidebar can slide up and down as the user scrolls up and down the page.
Depending on your content, you may need to adjust 800
pixel number. If your sidebar is so long that having it in a fixed position makes it so the bottom of the sidebar gets cut off, increase the 800
pixel number here to a higher number.
In the attributes for each sidebar item, if you use external_url
instead of url
, the theme will insert the link into an a href
element that opens in a blank target.
For example, the sidebar.html file contains the following code:
{% if folderitem.external_url %}
<li><a href="{{folderitem.external_url}}" target="_blank">{{folderitem.title}}</a></li>```
You can see that the `external_url` is a condition that applies a different formatting. Although this feature is available, I recommend putting any external navigation links in the top navigation bar instead of the side navigation bar.
## Sidebar item highlighting
The sidebar.html file inserts an `active` class into the sidebar element when the `url` attribute in the sidebar data file matches the page URL.
For example, the sidebar.html file contains the following code:
```liquid
{% elsif page.url == folderitem.url %}
<li class="active"><a href="{{folderitem.url | remove: "/"}}">{{folderitem.title}}</a></li>
If the page.url
matches the subfolderitem.url
, then an active
class gets applied. If not, the active
class does not get applied.
The page.url
in Jekyll is a site-wide variable. If you insert {{page.url}}
on a page, it will render as follows: /mydoc_sidebar_navigation.html. The url
attribute in the sidebar item must match the page URL in order to get the active
class applied.
This is why the url
value in the sidebar data file looks something like this:
- title: Understanding how the sidebar works
permalink: mydoc_understand_sidebar.html
output: web, pdf
Note that the url does not include the project folder where the file is stored. This is because the site uses permalinks, which pulls the topics out of subfolders and places them into the root directory when the site builds.
Now the page.url and the item.url can match and the active
class can get applied. With the active
class applied, the sidebar section remains open.
orzh-introduction
X-WAF-README
nginx-lua-module-zh-wiki
orange_about
pra_flame_how
orzh-introduction
X-WAF-README
nginx-lua-module-zh-wiki
orange_about
titlepage
tocpage
p1_landing_page
p1_sample1
p1_sample2
p1_sample3
p1_sample4
p1_sample5
p1_sample6
p1_sample7
titlepage
tocpage
p2_landing_page
p2_sample1
p2_sample2
p2_sample3
p2_sample4
p2_sample5
p2_sample6
p2_sample7
p2_sample8
p2_sample9
p2_sample10
p2_sample11
p2_sample12
p2_sample13
p2_sample14
titlepage
tocpage
p1_landing_page
p1_sample1
p1_sample2
p1_sample3
p1_sample4
p1_sample5
p1_sample6
p1_sample7
titlepage
tocpage
X-WAF-README
xwaf_installation
xwaf_depoly
xwaf_README
xwaf_advanced_readme
xwaf_getting_started
xwaf_faqs_readme
xwaf_roadmap
titlepage
tocpage
nginx-lua-module-zh-wiki
titlepage
tocpage
orange_api_server
orange_build_plugin
orange_dashboard_usage
orange_README
orange_basic_auth
orange_basic_info
orange_divide
orange_key_auth
orange_monitor
orange_rate_limiting
orange_redirect
orange_rewrite
orange_stat
orange_waf
orange_condition
orange_expression
orange_extraction
orange_extractor
orange_handle
orange_judge
orange_rule
orange_about
orange_contributing
orange_issues
orange_usages
titlepage
tocpage
add_new_lua_api
cosocket
get_req_body
get_url_param
helloworld
how_request_http
inline_var
install
install_on_centos
install_on_ubuntu
install_on_windows
install_osx
log_response
outtest
response
safe_sql
share_var
simple_api
sub_request
work_with_location
array_size
break
brief
build_env
call_user_func_array
capture
class
control_structrues
dot_diff
dummy_var
FFI
file
for
function_before_use
function_define
function_descrip
function_parameter
function_result
if_else
local
main
math_library
metatable
module_is_evil
module
not_nill
not_use_lib
not_use_module
object_oriented
operator
re
repeat
string_library
table_library
time_date_function
what_jit
while
pra_flame_how
pra_flame_install
pra_flame_what
pra_flame_when
pra_ngx_lua_allow_deny
pra_ngx_lua_block_io
pra_ngx_lua_cache
pra_ngx_lua_capture
pra_ngx_lua_continue_after_eof
pra_ngx_lua_debug
pra_ngx_lua_ffi
pra_ngx_lua_hot_load
pra_ngx_lua_how_one_instance_time
pra_ngx_lua_how_use_third_lib
pra_ngx_lua_keepalive
pra_ngx_lua_log
pra_ngx_lua_lua-limit
pra_ngx_lua_lua_opt
pra_ngx_lua_lua-variable-scope
pra_ngx_lua_on_abort
pra_ngx_lua_phase
pra_ngx_lua_resolve_the_domain_name
pra_ngx_lua_shared_get_keys
pra_ngx_lua_sleep
pra_ngx_lua_timer
pra_ngx_lua_use_case
pra_ngx_lua_whats_cosocket
pra_redis_auth_connect
pra_redis_dynamic_redis_module_method
pra_redis_out_package
pra_redis_pipeline
pra_redis_pub_sub_package
pra_redis_script
pra_redis_select-keeplive
pra_postgres_health_check
pra_postgres_how_to_use
pra_postgres_not_support_transaction
pra_postgres_sql_inject
pra_postgres_timeout
pra_nginx_balancer
pra_nginx_co-work_of_location
pra_nginx_if_is_evil
pra_nginx_match_uri
pra_nginx_nginx_brief
pra_nginx_nginx_local_pcre
pra_nginx_nginx_log
pra_nginx_nginx
pra_nginx_pitfalls_and_common_mistakes
pra_nginx_reverse_proxy
pra_nginx_static_file
titlepage
tocpage
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_scan_port
candylab_common_sites_log_system
candylab_graylog_clickhouse
candylab_clickhouse_basic
candylab_logs_and_gateway
candylab_sec_system_arch
candylab_logs_dsl_waf
candylab_opensock_list
candylab_opensock_practice
candylab_opensock_email
candylab_base_on_openresty_waf
candylab_dsl_waf
candylab_honeypot_system
candylab_monitor_redis
candylab_threat_replay
candylab_pcap_monitor
candylab_monitor_website
candylab_openrestyplus_waf
candylab_windows_bigdata
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
candylab_clickhouse_basic
mydoc_hyperlinks.html#automatedlinks
mydoc_hyperlinks.html#bookmarklinks
mydoc_pages.html#someIdTag
news
nginx-lua-module-zh-wiki
nginx-development-guide-zh
orange_about
X-WAF-README
pra_flame_how