Skip to content

Commit

Permalink
Updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@choldgraf
choldgraf committed May 20, 2022
1 parent 44cd965 commit 1ce96e7
Show file tree
Hide file tree
Showing 6 changed files with 283 additions and 274 deletions.
25 changes: 13 additions & 12 deletions docs/_data/config-header.yml
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
brand:
type: link
type: button
image: https://executablebooks.org/en/latest/_static/logo.svg
url: https://sphinx-book-theme.readthedocs.io
start:
Expand All @@ -23,22 +23,23 @@ start:
- content: Feature Voting
url: https://executablebooks.org/en/latest/feature-vote.html

- type: link
- type: button
content: Book gallery
external: true
newwindow: true
url: http://gallery.jupyterbook.org/


end:
- type: icon-links
icons:
- icon: fab fa-twitter-square
name: Twitter
- type: group
items:
- type: button
icon: fab fa-twitter-square
title: Twitter
url: https://twitter.com/executablebooks
- icon: fab fa-github-square
name: GitHub
- type: button
icon: fab fa-github-square
title: GitHub
url: https://github.com/executablebooks
- icon: fas fa-comments
name: Forum
- type: button
icon: fas fa-comments
title: Forum
url: https://github.com/orgs/executablebooks/discussions
172 changes: 103 additions & 69 deletions docs/customize/header.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -161,26 +161,101 @@ html_theme_options = {

The rest of these sections describe the components you can use:

### Link and text components
### Buttons

Buttons are flexible UI components that trigger various actions when clicked.
They can be links, or they can trigger arbitrary JavaScript that you provide.
Use them as call-to-action items, or as a way to trigger events on your page if you are using custom JavaScript.

Clicking a button can trigger one of two actions:

- **Link to an internal or external page**
- **Trigger a JavaScript function**

Buttons have three visual sections that you may control, that roughly follow this structure:

```html
<button>
<button-icon><button-image><button-content>
</button>
```

- **`icon`**: A small, square icon. May be configured with **FontAwesome** icons or a path to an image (local or remove).
- **`image`**: A larger image that may be rectangular. May be configured with **FontAwesome** icons or a path to an image (local or remove).
- **`content`**: Arbitrary text (or extra HTML) to put inside the button.

To add text and link components to header sections, use the following component configuration:
To add buttons components to header sections, use the following component configuration:

```python

# Provided as a list item to `start:` or `end:`
{
# Specifies a `text` component
"type": "text",
# The URL to which the link points
"url": "https://jupyterbook.org",
# The text to be displayed
"content": "Jupyter Book",
# Specifies the `button` component
"type": "button",

## Controls button behavior ##
# If provided, the button will be a link to another page.
"url": "https://google.com",
# If provided, clicking the button will trigger this JavaScript.
"onclick": "SomeFunction()",

## Controls button style ##
# An icon that will be displayed before the text
# Can be a set of fontawesome classes, or a path to an image
"icon": "fas fa-bars",
# An image path that will be displayed before the text
"image": "https://executablebooks.org/en/latest/_static/logo.svg",
# The text that will be displayed inside the button.
"content": "My button's text",
# An optional list of classes to add
"classes": ["one", "two"]
},
}
```

To add text without a link, simply omit the `url:` parameter.
Note tha **url** and **onclick** cannot both be provided in the same button's configuration.

#### Button icons

There are two kinds of icons you can control with the `icon` parameter:

- **FontAwesome icons**: FontAwesome icon classes like `fas fa-arrow-right`. See [the FontAwesome documentation](https://fontawesome.com/icons) for a list of classes and icons. For example:

```python
# Provided as a list item to `start:` or `end:`
{
# Specifies the `button` component
"type": "button",
"icon": "fab fa-github"
"url": "https://github.com"
}
```
- **A path to an image**: Any local image you include with your documentation.

For example, with a remote image:

```python
# Provided as a list item to `start:` or `end:`
{
# Specifies the `button` component
"type": "button",
"image": "https://executablebooks.org/en/latest/_static/logo.svg"
"url": "https://executablebooks.org"
}
```

With a local image:

```python
# Provided as a list item to `start:` or `end:`
{
# Specifies the `button` component
"type": "button",
"image": "./_static/myimage.png"
"url": "https://executablebooks.org"
}
```

Finally, if a button is configured **only with an icon**, it will have a special class `icon-button` added to it that will make it contract slightly in size and spacing.

### Dropdown menus

Expand All @@ -196,7 +271,7 @@ To add dropdown components to header sections, use the following component confi
"type": "dropdown",
# Text to be displayed on the button
"content": "EBP Projects",
# A list of dropdown links. Each defines a content string and a url
# A list of dropdown links. Each is a configuration for a button.
"items": [
{
"url": "https://executablebooks.org",
Expand All @@ -212,79 +287,38 @@ To add dropdown components to header sections, use the following component confi
},
```

### Icon links
### Groups

You can add a list of icon links to your header that link to external sites and services.
These are often used to link to social media accoutns like GitHub, Twitter, discussion forums, etc.
They will be displayed horizontally whether on wide or narrow screens.
Groups are a way of telling the theme that several UI components should be grouped together.
They will have a wrapping container, will have less spacing between them, and will be displayed _horizontally_ on narrow screens.

There are two kinds of icons you can control with `icon-links`:

- **FontAwesome icons**: FontAwesome icon classes like `fas fa-arrow-right`. See [the FontAwesome documentation](https://fontawesome.com/icons) for a list of classes and icons.
- **A path to an image**: Any local image you include with your documentation.

To add icon link components to header sections, use the following component configuration:
For example, to group several icon buttons together use a configuration like so:

```python
# Provided as a list item to `start:` or `end:`
{
# Specifies the `icon-links` component
"type": "icon-links",
# A list of icon links to include
"icons": [
# Configuration for icon one uses FontAwesome
# Specifies a `group` type
"type": "group",
# A list of group items. Each is a configuration for a button.
"items": [
{
# Specifies that this icon is a FontAwesome icon
"type": "fontawesome",
# A url for icon one
"url": "https://twitter.com/executablebooks",
# A tooltip for icon one
"name": "Twitter",
# A FontAwesome icon class
"icon": "fab fa-twitter-square",
"icon": "fab fa-github",
"url": "https://github.com
},
# Configuration for icon two uses a local image path
{
# Specifies that this icon is a local image
"type": "local",
# A url for icon two
"url": "https://github.com/orgs/executablebooks/discussions",
# A tooltip for icon two
"name": "Discussions image",
# A path to a local image relative to conf.py
"icon": "./path/to/image.png",
"icon": "fab fa-twitter",
"url": "https://twitter.com
},
{
"icon": "fab fa-discourse",
"url": "https://discourse.com
},
],
},
```

### Buttons

Buttons are larger and more visually-noticeable.
They can either be links, or they can trigger arbitrary JavaScript that you provide.
Use them as call-to-action items, or as a way to trigger events on your page if you are using custom JavaScript.

To add buttons components to header sections, use the following component configuration:

```python

# Provided as a list item to `start:` or `end:`
{
# Specifies the `button` component
"type": "button",
# The text that will be displayed inside the button.
"content": "end",
# If provided, the button will be a link to another page.
"url": "https://google.com",
# If provided, clicking the button will trigger this JavaScript.
"onclick": "SomeFunction()",
# An optional list of classes to add
"classes": ["one", "two"]
}
},
```

Note tha **url** and **onclick** cannot both be provided in the same button's configuration.

### HTML Snippets

You may provide custom HTML snippets that are inserted into the header as-is.
Expand Down
Loading

0 comments on commit 1ce96e7

Please sign in to comment.