Skip to content

Commit e32af5f

Browse files
bollwyvlbollwyvl
authored
ENH: add icon_links option for custom navbar icons (with docs and pypi example) (#293)
1 parent 93b5115 commit e32af5f

11 files changed

+155
-51
lines changed

‎docs/conf.py

+7
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,13 @@
6868
],
6969
"github_url": "https://github.com/pandas-dev/pydata-sphinx-theme",
7070
"twitter_url": "https://twitter.com/pandas_dev",
71+
"icon_links": [
72+
{
73+
"name": "PyPI",
74+
"url": "https://pypi.org/project/pydata-sphinx-theme",
75+
"icon": "fas fa-box",
76+
}
77+
],
7178
"use_edit_page_button": True,
7279
"show_toc_level": 1,
7380
# "navbar_align": "right", # For testing that the navbar items align properly

‎docs/user_guide/configuring.rst

+67-7
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ doc path's _static folder, and use the following configuration:
1919
2020
html_logo = "_static/logo.png"
2121
22-
The logo links to ``master_doc`` (usually the first page of your documentation) by default.
22+
The logo links to ``master_doc`` (usually the first page of your documentation) by default.
2323
If you'd like it to link to another page or use an external link instead, use the following configuration:
2424

2525
.. code:: python
@@ -29,20 +29,80 @@ If you'd like it to link to another page or use an external link instead, use th
2929
}
3030
3131
32-
Configure social media buttons
33-
==============================
32+
Configure icon links
33+
====================
3434

35-
If you'd like social media buttons to show up to the right of your nav bar, use the
35+
If you'd like icon links to show up to the right of your main navigation bar, use the
3636
following configuration:
3737

3838
.. code:: python
3939
4040
html_theme_options = {
41-
"github_url": "https://github.com/<your-org>/<your-repo>",
42-
"gitlab_url": "https://gitlab.com/<your-org>/<your-repo>",
43-
"twitter_url": "https://twitter.com/<your-handle>",
41+
...
42+
"icon_links": [
43+
{
44+
"name": "GitHub",
45+
"url": "https://github.com/<your-org>/<your-repo>",
46+
"icon": "fab fa-github-square",
47+
},
48+
{
49+
"name": "GitLab",
50+
"url": "https://gitlab.com/<your-org>/<your-repo>",
51+
"icon": "fab fa-gitlab",
52+
},
53+
{
54+
"name": "Twitter",
55+
"url": "https://twitter.com/<your-handle>",
56+
"icon": "fab fa-twitter-square",
57+
},
58+
],
59+
...
60+
}
61+
62+
63+
The value of ``icon`` can be any full
64+
`FontAwesome 5 Free <https://fontawesome.com/icons?d=gallery&m=free>`__ icon.
65+
In addition to the main icon class, e.g. ``fa-cat``, the "style" class must
66+
also be provided e.g. `fab` for *branding*, or `fas` for *solid*.
67+
68+
69+
.. Hint::
70+
71+
To get custom colors like "Twitter blue", use the following in your CSS,
72+
e.g. ``custom.css``:
73+
74+
.. code:: css
75+
76+
i.fa-twitter-square:before {
77+
color: #55acee;
78+
}
79+
80+
This has already been added for the brands that have *shortcuts*.
81+
82+
The below are shortcuts for commonly-used services, but may be removed in a future
83+
release in favor of ``icon_links``:
84+
85+
.. code:: python
86+
87+
html_theme_options = {
88+
...
89+
"github_url": "https://github.com/<your-org>/<your-repo>",
90+
"gitlab_url": "https://gitlab.com/<your-org>/<your-repo>",
91+
"twitter_url": "https://twitter.com/<your-handle>",
92+
...
4493
}
4594
95+
Additionally, the screen-reader accessible label for this menu can be configured:
96+
97+
.. code:: python
98+
99+
html_theme_options = {
100+
...
101+
"icon_links_label": "Quick Links",
102+
...
103+
}
104+
105+
46106
Adding external links to your nav bar
47107
=====================================
48108

‎pydata_sphinx_theme/docs-navbar.html

+3-25
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
21
<div class="container-xl">
32

43

@@ -37,33 +36,12 @@
3736
{% endfor %}
3837
</ul>
3938

40-
4139
{% if theme_search_bar_position == 'navbar' %}
4240
{%- include "search-field.html" %}
4341
{% endif %}
4442

45-
<ul class="navbar-nav">
46-
{% if theme_github_url | length > 2 %}
47-
<li class="nav-item">
48-
<a class="nav-link" href="{{ theme_github_url }}" target="_blank" rel="noopener">
49-
<span><i class="fab fa-github-square"></i></span>
50-
</a>
51-
</li>
52-
{% endif %}
53-
{% if theme_gitlab_url | length > 2 %}
54-
<li class="nav-item">
55-
<a class="nav-link" href="{{ theme_gitlab_url }}" target="_blank" rel="noopener">
56-
<span><i class="fab fa-gitlab"></i></span>
57-
</a>
58-
</li>
59-
{% endif %}
60-
{% if theme_twitter_url | length > 2 %}
61-
<li class="nav-item">
62-
<a class="nav-link" href="{{ theme_twitter_url }}" target="_blank" rel="noopener">
63-
<span><i class="fab fa-twitter-square"></i></span>
64-
</a>
65-
</li>
66-
{% endif %}
67-
</ul>
43+
{%- block icon_links -%}
44+
{%- include "icon-links.html" with context -%}
45+
{%- endblock %}
6846
</div>
6947
</div>

‎pydata_sphinx_theme/icon-links.html

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{%- macro icon_link_nav_item(url, icon, name) -%}
2+
{%- if url | length > 2 %}
3+
<li class="nav-item">
4+
<a class="nav-link" href="{{ url }}" rel="noopener" target="_blank" title="{{ _(name) }}">
5+
<span><i class="{{ icon }}"></i></span>
6+
<label class="sr-only">{{ _(name) }}</label>
7+
</a>
8+
</li>
9+
{%- endif -%}
10+
{%- endmacro -%}
11+
12+
<ul id="navbar-icon-links" class="navbar-nav" aria-label="{{ _(theme_icon_links_label) }}">
13+
{%- block icon_link_shortcuts -%}
14+
{{ icon_link_nav_item(theme_github_url, "fab fa-github-square", "GitHub") -}}
15+
{{ icon_link_nav_item(theme_gitlab_url, "fab fa-gitlab", "GitLab") -}}
16+
{{ icon_link_nav_item(theme_twitter_url, "fab fa-twitter-square", "Twitter") -}}
17+
{% endblock -%}
18+
{%- for icon_link in theme_icon_links -%}
19+
{{ icon_link_nav_item(icon_link["url"], icon_link["icon"], icon_link["name"]) -}}
20+
{%- endfor %}
21+
</ul>

‎pydata_sphinx_theme/static/css/index.0e366ba14472447708f75ccb7d8f24a3.css renamed to ‎pydata_sphinx_theme/static/css/index.4ea0a4617f49cfd39b5b9e9540ffc872.css

+1-1
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎pydata_sphinx_theme/static/js/index.9ab83e9ee01d4093105a.js renamed to ‎pydata_sphinx_theme/static/js/index.bf572f7d6dfb3e591c72.js

File renamed without changes.

‎pydata_sphinx_theme/static/webpack-macros.html

+3-3
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,13 @@
1717

1818
{% macro head_pre_bootstrap() %}
1919
<link href="{{ pathto('_static/css/theme.css', 1) }}" rel="stylesheet" />
20-
<link href="{{ pathto('_static/css/index.0e366ba14472447708f75ccb7d8f24a3.css', 1) }}" rel="stylesheet" />
20+
<link href="{{ pathto('_static/css/index.4ea0a4617f49cfd39b5b9e9540ffc872.css', 1) }}" rel="stylesheet" />
2121
{% endmacro %}
2222

2323
{% macro head_js_preload() %}
24-
<link rel="preload" as="script" href="{{ pathto('_static/js/index.9ab83e9ee01d4093105a.js', 1) }}">
24+
<link rel="preload" as="script" href="{{ pathto('_static/js/index.bf572f7d6dfb3e591c72.js', 1) }}">
2525
{% endmacro %}
2626

2727
{% macro body_post() %}
28-
<script src="{{ pathto('_static/js/index.9ab83e9ee01d4093105a.js', 1) }}"></script>
28+
<script src="{{ pathto('_static/js/index.bf572f7d6dfb3e591c72.js', 1) }}"></script>
2929
{% endmacro %}

‎pydata_sphinx_theme/theme.conf

+3
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,10 @@ use_edit_page_button = False
1010
external_links =
1111
logo_link =
1212
github_url =
13+
gitlab_url =
1314
twitter_url =
15+
icon_links_label = Icon Links
16+
icon_links =
1417
google_analytics_id =
1518
show_prev_next = True
1619
search_bar_text = Search the docs ...

‎src/scss/index.scss

+25-14
Original file line numberDiff line numberDiff line change
@@ -408,25 +408,36 @@ table.field-list {
408408
color: #e83e8c;
409409
}
410410

411-
/* Social media buttons */
412-
413-
i {
414-
&.fab {
415-
vertical-align: middle;
416-
font-style: normal;
417-
font-size: 1.5rem;
418-
line-height: 1.25;
419-
}
411+
/* Icon Links */
420412

421-
&.fa-github-square:before {
422-
color: #333;
423-
}
413+
#navbar-icon-links {
414+
i {
415+
&.fa,
416+
&.fab,
417+
&.far,
418+
&.fas{
419+
vertical-align: middle;
420+
font-style: normal;
421+
font-size: 1.5rem;
422+
line-height: 1.25;
423+
}
424+
425+
/* Social media buttons */
426+
&.fa-github-square:before {
427+
color: #333;
428+
}
429+
430+
&.fa-twitter-square:before {
431+
color: #55acee;
432+
}
424433

425-
&.fa-twitter-square:before {
426-
color: #55acee;
434+
&.fa-gitlab:before {
435+
color: #548
436+
}
427437
}
428438
}
429439

440+
430441
/* TOC section headers */
431442

432443
.tocsection {

‎tests/test_build/icon_links.html

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
<ul aria-label="Quick Links" class="navbar-nav" id="navbar-icon-links">
2+
<li class="nav-item">
3+
<a class="nav-link" href="x://y/z" rel="noopener" target="_blank" title="GitHub">
4+
<span>
5+
<i class="fab fa-github-square">
6+
</i>
7+
</span>
8+
<label class="sr-only">
9+
GitHub
10+
</label>
11+
</a>
12+
</li>
13+
<li class="nav-item">
14+
<a class="nav-link" href="x://y/z" rel="noopener" target="_blank" title="Xyz">
15+
<span>
16+
<i class="fax fa-xyz">
17+
</i>
18+
</span>
19+
<label class="sr-only">
20+
Xyz
21+
</label>
22+
</a>
23+
</li>
24+
</ul>

‎tests/test_build/navbar_ix.html

+1-1
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,6 @@
1616
</a>
1717
</li>
1818
</ul>
19-
<ul class="navbar-nav">
19+
<ul aria-label="Icon Links" class="navbar-nav" id="navbar-icon-links">
2020
</ul>
2121
</div>

0 commit comments

Comments
 (0)