Skip to content

Commit

Permalink
add new tabs extension (experimental)
Browse files Browse the repository at this point in the history
with the tabs extension, lists can be formatted as
multiple tabs that the user can toggle between.
The required markdown can still be rendered as a normal list in github.
This feature is experimental and might be subject to change!
  • Loading branch information
jothepro committed Feb 15, 2023
1 parent bbaaea4 commit dd9216c
Show file tree
Hide file tree
Showing 9 changed files with 301 additions and 91 deletions.
3 changes: 2 additions & 1 deletion Doxyfile
Original file line number Diff line number Diff line change
Expand Up @@ -1392,7 +1392,8 @@ HTML_EXTRA_FILES = doxygen-awesome-darkmode-toggle.js \
doxygen-awesome-fragment-copy-button.js \
doxygen-awesome-paragraph-link.js \
doxygen-custom/toggle-alternative-theme.js \
doxygen-awesome-interactive-toc.js
doxygen-awesome-interactive-toc.js \
doxygen-awesome-tabs.js

# The HTML_COLORSTYLE tag can be used to specify if the generated HTML output
# should be rendered with a dark or light theme.
Expand Down
51 changes: 25 additions & 26 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,40 +64,39 @@ There is two layout options. Choose one of them and configure Doxygen accordingl

</div>

<div class="tabbed">

- <b class="tab-title">1️⃣ Base Theme </b>
Comes with the typical Doxygen titlebar. Optionally the treeview in the sidebar can be enabled.

#### Base Theme (1)
Required files: `doxygen-awesome.css`

Comes with the typical Doxygen titlebar. Optionally the treeview in the sidebar can be enabled.
Required `Doxyfile` configuration:
```
GENERATE_TREEVIEW = YES # optional. Also works without treeview
DISABLE_INDEX = NO
FULL_SIDEBAR = NO
HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css
HTML_COLORSTYLE = LIGHT # required with Doxygen >= 1.9.5
```

Required files: `doxygen-awesome.css`
- <b class="tab-title">2️⃣ Sidebar-Only Theme </b>
Hides the top titlebar to give more space to the content. The treeview must be enabled in order for this theme to work.

Required `Doxyfile` configuration:
```
GENERATE_TREEVIEW = YES # optional. Also works without treeview
DISABLE_INDEX = NO
FULL_SIDEBAR = NO
HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css
HTML_COLORSTYLE = LIGHT # required with Doxygen >= 1.9.5
```

#### Sidebar-Only Theme (2)

Hides the top titlebar to give more space to the content. The treeview must be enabled in order for this theme to work.
Required files: `doxygen-awesome.css`, `doxygen-awesome-sidebar-only.css`

Required files: `doxygen-awesome.css`, `doxygen-awesome-sidebar-only.css`
Required `Doxyfile` configuration:
```
Required `Doxyfile` configuration:
```
GENERATE_TREEVIEW = YES # required!
DISABLE_INDEX = NO
FULL_SIDEBAR = NO
HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css \
doxygen-awesome-css/doxygen-awesome-sidebar-only.css
HTML_COLORSTYLE = LIGHT # required with Doxygen >= 1.9.5
```
GENERATE_TREEVIEW = YES # required!
DISABLE_INDEX = NO
FULL_SIDEBAR = NO
HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css \
doxygen-awesome-css/doxygen-awesome-sidebar-only.css
HTML_COLORSTYLE = LIGHT # required with Doxygen >= 1.9.5
```

</div>

**Caution**:
- This theme is not compatible with the `FULL_SIDEBAR = YES` option provided by Doxygen!
Expand Down
11 changes: 8 additions & 3 deletions docs/customization.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,13 +28,16 @@ html {

For dark-mode overrides you have to choose where to put them, depending on whether the dark-mode toggle extension is installed or not:

- dark-mode toggle is installed:
<div class="tabbed">

- <b class="tab-title">dark-mode toggle is installed</b>
```css
html.dark-mode {
/* define dark-mode variable overrides here if you DO use doxygen-awesome-darkmode-toggle.js */
}
```
- dark-mode toggle is **NOT** installed. The dark-mode is enabled automatically depending on the system preference:
- <b class="tab-title">dark-mode toggle is **NOT** installed</b>
The dark-mode is enabled automatically depending on the system preference:
```css
@media (prefers-color-scheme: dark) {
html:not(.light-mode) {
Expand All @@ -43,6 +46,8 @@ For dark-mode overrides you have to choose where to put them, depending on wheth
}
```

</div>

### Available variables

The following list gives an overview of the variables defined in [`doxygen-awesome.css`](https://github.com/jothepro/doxygen-awesome-css/blob/main/doxygen-awesome.css).
Expand Down Expand Up @@ -73,7 +78,7 @@ All variables are defined at the beginning of the stylesheet.
| **Code Fragment Colors**:<br>Color-Scheme of multiline codeblocks |||
| `--fragment-background` | <code style="background:#F8F9FA;color:black">#F8F9FA</code> | <code style="background:#282c34;color:white">#282c34</code> |
| `--fragment-foreground` | <code style="background:#37474F;color:white">#37474F</code> | <code style="background:#dbe4eb;color:black">#dbe4eb</code> |
| **Arrow Opacity**:<br>By default the arrows in the sidebar are only visible on hover. You can override this behaviour so they are visible all the time. |||
| **Arrow Opacity**:<br>By default the arrows in the sidebar are only visible on hover. You can override this behavior so they are visible all the time. |||
| `--side-nav-arrow-opacity` | `0` | |
| `--side-nav-arrow-hover-opacity` | `0.9` | |
| ...and many more |||
Expand Down
46 changes: 46 additions & 0 deletions docs/extensions.md
Original file line number Diff line number Diff line change
Expand Up @@ -184,6 +184,52 @@ Hiding the TOC on small screens can be disabled. It is still interactive and can
DoxygenAwesomeInteractiveToc.hideMobileMenu = false
```

## Tabs

@note Experimental feature! Please report bugs [here](https://github.com/jothepro/doxygen-awesome-css/issues).


This extension allows to arrange list content in tabs:

<div class="tabbed">

- <b class="tab-title">Tab 1</b> This is the content of tab 1
- <b class="tab-title">Tab 2</b> This is the content of tab 2

</div>


### Installation

1. Add the required resources in your `Doxyfile`:
- **HTML_EXTRA_FILES:** `doxygen-awesome-tabs.js`
2. In the `header.html` template, include `doxygen-awesome-tabs.js` at the end of the `<head>` and then initialize it:
```html
<html>
<head>
<!-- ... other metadata & script includes ... -->
<script type="text/javascript" src="$relpath^doxygen-awesome-tabs.js"></script>
<script type="text/javascript">
DoxygenAwesomeTabs.init()
</script>
</head>
<body>
```

### Usage

Each List that is supposed to be displayed as tabs has to be wrapped with the `tabbed` CSS class.
Each Item in the list must start with an element that has the class `tab-title`. It will then be used as tab title.

```md
<div class="tabbed">

- <b class="tab-title">Tab 1</b> This is the content of tab 1
- <b class="tab-title">Tab 2</b> This is the content of tab 2

</div>
```

<span class="next_section_button">

Read Next: [Customization](customization.md)
Expand Down
97 changes: 47 additions & 50 deletions docs/tricks.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,18 +13,21 @@ DOT_IMAGE_FORMAT = svg
DOT_TRANSPARENT = YES
```

In case `INTERACTIVE_SVG = YES` is set in the Doxyfile, make sure to add this CSS snippet in order for the interactive svg viewer to be
rendered correctly:
In case `INTERACTIVE_SVG = YES` is set in the Doxyfile, all user-defined dotgraphs must be wrapped with the `interactive_dotgraph` CSS class in order for them to be rendered correctly:

```css
.dotgraph iframe {
max-width: 100%;
}
```md
<div class="interactive_dotgraph">

\dotfile graph.dot

</div>
```

@note Both the default overflow scrolling behavior in this theme and the interactive editor enabled by `INTERACTIVE_SVG` are unsatisfying workarounds IMHO. Consider designing your graphs to be narrow enough to fit the page to avoid scrolling.

## Disable Dark Mode

If for some reason you don't want the theme to automatically switch to dark mode depending on the browser preference,
If you don't want the theme to automatically switch to dark mode depending on the browser preference,
you can disable dark mode by adding the `light-mode` class to the html-tag in the header template:

```html
Expand All @@ -38,7 +41,7 @@ The same can be done to always enable dark-mode:
```


**This only works if you don't use the dark-mode toggle extension.**
@warning This only works if you don't use the dark-mode toggle extension.

## Choosing Sidebar Width

Expand All @@ -62,64 +65,58 @@ TREEVIEW_WIDTH = 335

## Formatting Tables

By default tables in this theme are left aligned and as wide as required to fit their content.
By default tables in this theme are left-aligned and as wide as required to fit their content.
Those properties can be changed for individual tables.

### Centering

Tables can be centered by wrapping them in the `<center>` HTML-tag.

**Example:**

```md
<center>

| This table | is centered |
|------------|----------------------|
| test 1 | test 2 |

</center>
```

**Result:**
<div class="tabbed">

- <span class="tab-title">Code</span>
```md
<center>
| This table | is centered |
|------------|----------------------|
| test 1 | test 2 |
</center>
```
- <span class="tab-title">Result</span>
<center>
| This table | is centered |
|------------|----------------------|
| test 1 | test 2 |
</center>

<center>
</div>

| This table | is centered |
|------------|----------------------|
| test 1 | test 2 |

</center>

### Full Width

To make tables span the full width of the page, no matter how wide the content is, wrap the table in the `full_width_table` CSS class.

@warning Apply with caution! This breaks the overflow scrolling on small screens!

**Example:**

```md
<div class="full_width_table">

| This table | fills the full width |
|------------|----------------------|
| test 1 | test 2 |
@warning Apply with caution! This breaks the overflow scrolling of the table. Content might be cut of on small screens!

<div class="tabbed">

- <span class="tab-title">Code</span>
```md
<div class="full_width_table">
| This table | spans the full width |
|------------|----------------------|
| test 1 | test 2 |
</div>
```
- <span class="tab-title">Result</span>
<div class="full_width_table">
| This table | spans the full width |
|------------|----------------------|
| test 1 | test 2 |
</div>

</div>
```

**Result:**

<div class="full_width_table">

| This table | fills the full width |
|------------|----------------------|
| test 1 | test 2 |

</div>



<span class="next_section_button">

Expand Down
70 changes: 70 additions & 0 deletions doxygen-awesome-tabs.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
/**
Doxygen Awesome
https://github.com/jothepro/doxygen-awesome-css
MIT License
Copyright (c) 2023 jothepro
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
*/

class DoxygenAwesomeTabs {

static init() {
window.addEventListener("load", () => {
document.querySelectorAll(".tabbed:not(:empty)").forEach((tabbed, tabbedIndex) => {
let tabLinkList = []
tabbed.querySelectorAll("li").forEach((tab, tabIndex) => {
tab.id = "tab_" + tabbedIndex + "_" + tabIndex
let header = tab.querySelector(".tab-title")
let tabLink = document.createElement("button")
tabLink.classList.add("tab-button")
tabLink.appendChild(header)
tabLink.addEventListener("click", () => {
tabbed.querySelectorAll("li").forEach((tab) => {
tab.classList.remove("selected")
})
tabLinkList.forEach((tabLink) => {
tabLink.classList.remove("active")
})
tab.classList.add("selected")
tabLink.classList.add("active")
})
tabLinkList.push(tabLink)
if(tabIndex == 0) {
tab.classList.add("selected")
tabLink.classList.add("active")
}
})
let tabsOverview = document.createElement("div")
tabsOverview.classList.add("tabs-overview")
let tabsOverviewContainer = document.createElement("div")
tabsOverviewContainer.classList.add("tabs-overview-container")
tabLinkList.forEach((tabLink) => {
tabsOverview.appendChild(tabLink)
})
tabsOverviewContainer.appendChild(tabsOverview)
tabbed.before(tabsOverviewContainer)
})
})
}
}
Loading

0 comments on commit dd9216c

Please sign in to comment.