all should work now
This commit is contained in:
219
README.md
219
README.md
@@ -1,10 +1,20 @@
|
||||
# Menu Plugin for Obsidian
|
||||
# Obsidian Menus
|
||||
|
||||
Create custom navigation menus in Obsidian using simple code blocks. Supports internal links, external URLs, and local file links with built-in themes and full customization.
|
||||
Create simple, stylable menus from code blocks. You write links inside a `menu` code block, and the plugin renders:
|
||||
- a single div with class `menu-container`
|
||||
- a set of anchor tags inside it
|
||||
|
||||
You can:
|
||||
- Pick a built-in template (default, minimal, slate, horizon, aether)
|
||||
- Use your own CSS class (no plugin CSS applied)
|
||||
- Override styles using a small, safe set of YAML-like variables
|
||||
- Mix template + extra classes (e.g., `layout: horizon wide`)
|
||||
|
||||
CSS stays clean and predictable.
|
||||
|
||||
## Basic Usage
|
||||
|
||||
Create a menu using a `menu` code block with one of the built-in layouts:
|
||||
Create a menu using a `menu` code block with one of the built-in templates:
|
||||
|
||||
````markdown
|
||||
```menu
|
||||
@@ -16,32 +26,21 @@ layout: default
|
||||
```
|
||||
````
|
||||
|
||||
## Built-in Layouts
|
||||
- `[[Note]]` or `[[Note|Alias]]` creates internal links.
|
||||
- `[Text](https://example.com)` creates web links.
|
||||
- `[Text](file:///C:/path/to/file)` opens local files/folders.
|
||||
|
||||
### `default`
|
||||
Standard buttons with borders and backgrounds
|
||||
````markdown
|
||||
```menu
|
||||
layout: default
|
||||
[[Dashboard]]
|
||||
[GitHub](https://github.com)
|
||||
[Files](file:///C:/Users/Documents)
|
||||
```
|
||||
````
|
||||
## Built-in Templates
|
||||
|
||||
### `minimal`
|
||||
Clean text links with subtle colors
|
||||
````markdown
|
||||
```menu
|
||||
layout: minimal
|
||||
[[Notes]]
|
||||
[Web](https://example.com)
|
||||
[Folder](file:///C:/Projects)
|
||||
```
|
||||
````
|
||||
Available out of the box:
|
||||
- default
|
||||
- minimal
|
||||
- slate
|
||||
- horizon
|
||||
- aether
|
||||
|
||||
Example:
|
||||
|
||||
### `slate`
|
||||
Solid background buttons
|
||||
````markdown
|
||||
```menu
|
||||
layout: slate
|
||||
@@ -50,37 +49,95 @@ layout: slate
|
||||
```
|
||||
````
|
||||
|
||||
### `horizon`
|
||||
Modern outlined style
|
||||
You can also add extra classes like `wide` next to the layout:
|
||||
|
||||
````markdown
|
||||
```menu
|
||||
layout: horizon
|
||||
layout: horizon wide
|
||||
[[Dashboard]]
|
||||
[Resources](https://example.com)
|
||||
```
|
||||
````
|
||||
|
||||
### `aether`
|
||||
Grid layout with equal-width items
|
||||
Note: Built-in template CSS only applies when a built-in layout is selected. Internally, the container gets a `data-layout="..."` attribute which gates the plugin CSS. If you don’t select a built-in layout, none of the plugin CSS will affect your menu.
|
||||
|
||||
## Custom CSS Class Mode (No Plugin CSS)
|
||||
|
||||
Use your own CSS by providing a custom class via `class:` or `layout:` with a non-built-in value. In this mode, the plugin does not apply any of its CSS. It only renders the HTML and exposes inline CSS variables from the YAML-like overrides.
|
||||
|
||||
````markdown
|
||||
```menu
|
||||
layout: aether
|
||||
[[Projects]]
|
||||
[GitHub](https://github.com)
|
||||
[Documents](file:///C:/Users/Documents)
|
||||
class: my-menu wide
|
||||
bg: #111
|
||||
text: #eee
|
||||
hover-text: #0af
|
||||
internal-hover-text: orange
|
||||
|
||||
[[Home]]
|
||||
[Web](https://example.com)
|
||||
[Folder](file:///C:/Projects)
|
||||
```
|
||||
````
|
||||
|
||||
## Link Types
|
||||
Then, in a CSS snippet:
|
||||
|
||||
- **Internal**: `[[Note Name]]` or `[[Note Name|Display Text]]`
|
||||
- **External**: `[Display Text](https://example.com)`
|
||||
- **Files**: `[Display Text](file:///C:/path/to/file)`
|
||||
```css
|
||||
/* Example custom styling */
|
||||
.menu-container.my-menu {
|
||||
display: flex;
|
||||
gap: 0.5rem;
|
||||
flex-wrap: wrap;
|
||||
}
|
||||
|
||||
## Color Customization
|
||||
.menu-container.my-menu a {
|
||||
text-decoration: none;
|
||||
padding: 0.5rem 0.8rem;
|
||||
border-radius: 6px;
|
||||
color: var(--text, var(--text-normal));
|
||||
background: var(--bg, transparent);
|
||||
border: 1px solid var(--border, var(--background-modifier-border));
|
||||
}
|
||||
|
||||
Add color properties using YAML syntax:
|
||||
.menu-container.my-menu a:hover {
|
||||
color: var(--hover-text, var(--text-accent));
|
||||
background: var(--hover-bg, transparent);
|
||||
border-color: var(--hover-border, var(--text-accent));
|
||||
}
|
||||
```
|
||||
|
||||
## YAML-like Overrides (Safe Whitelist)
|
||||
|
||||
The code block supports a small set of variables. No raw CSS properties are accepted in the code block. If you need full CSS power, use a CSS snippet in your IDE.
|
||||
|
||||
Global variables:
|
||||
- bg
|
||||
- text
|
||||
- border
|
||||
- font
|
||||
- hover-text
|
||||
- hover-bg
|
||||
- hover-border
|
||||
- hover-font
|
||||
|
||||
Per link type variants (prefix with internal-, external-, file-):
|
||||
- internal-bg, internal-text, internal-border, internal-font
|
||||
- internal-hover-text, internal-hover-bg, internal-hover-border, internal-hover-font
|
||||
- external-... (same set)
|
||||
- file-... (same set)
|
||||
|
||||
Naming aliases supported:
|
||||
- text-hover -> hover-text
|
||||
- bg-hover -> hover-bg
|
||||
- border-hover -> hover-border
|
||||
- font-hover -> hover-font
|
||||
- accent -> hover-text (and internal-accent/external-accent/file-accent -> corresponding -hover-text)
|
||||
|
||||
Behavior of keys:
|
||||
- bg applies to the buttons (anchors), not the container
|
||||
- hover-* applies to the hover state of the buttons
|
||||
- type-specific keys (e.g., internal-text) override the global ones for that link type
|
||||
|
||||
Examples (template mode):
|
||||
````markdown
|
||||
```menu
|
||||
layout: default
|
||||
@@ -88,49 +145,51 @@ bg: #1a1a1a
|
||||
text: #ffffff
|
||||
hover-text: #ff6b6b
|
||||
border: #333333
|
||||
|
||||
[[Home]]
|
||||
[GitHub](https://github.com)
|
||||
```
|
||||
````
|
||||
|
||||
### Global Color Variables
|
||||
- `bg`: Background color
|
||||
- `text`: Text color
|
||||
- `border`: Border color
|
||||
- `hover-text`: Hover text color
|
||||
- `hover-bg`: Hover background
|
||||
- `hover-border`: Hover border color
|
||||
- `font`: Font family
|
||||
|
||||
### Link-Type Specific Colors
|
||||
Customize each link type individually:
|
||||
|
||||
Per-link-type overrides:
|
||||
````markdown
|
||||
```menu
|
||||
layout: minimal
|
||||
internal-text: #00ff00
|
||||
external-text: #ff6600
|
||||
file-text: #0066ff
|
||||
internal-font: "Arial"
|
||||
internal-font: "Fira Code"
|
||||
external-font: "Georgia"
|
||||
file-font: "Arial"
|
||||
|
||||
[[Internal Link]]
|
||||
[External Link](https://example.com)
|
||||
[File Link](file:///C:/Documents)
|
||||
```
|
||||
````
|
||||
|
||||
**Available for each type** (`internal`, `external`, `file`):
|
||||
- `{type}-text`: Text color
|
||||
- `{type}-bg`: Background color
|
||||
- `{type}-border`: Border color
|
||||
- `{type}-font`: Font family
|
||||
- `{type}-hover-text`: Hover text color
|
||||
- `{type}-hover-bg`: Hover background
|
||||
- `{type}-hover-border`: Hover border color
|
||||
## Link Types
|
||||
|
||||
## Advanced Examples
|
||||
- Internal: `[[Note Name]]` or `[[Note Name|Display Text]]`
|
||||
- External: `[Display Text](https://example.com)`
|
||||
- Files: `[Display Text](file:///C:/path/to/file)`
|
||||
|
||||
### Gradient Background
|
||||
Behavior:
|
||||
- Internal links open within Obsidian.
|
||||
- External links open in your browser.
|
||||
- File links open via the OS.
|
||||
|
||||
## Notes
|
||||
|
||||
- Use either `layout:` or `class:`. If the value contains a built-in template, the template is applied. Otherwise, it’s treated as a pure CSS class (no plugin CSS).
|
||||
- If no `layout:` or `class:` is provided, `layout: default` is assumed.
|
||||
- Colors support hex, rgb, hsl, CSS variables, and gradients.
|
||||
- Font names with spaces need quotes: `font: "Work Sans"`.
|
||||
- You can append additional classes after the layout or class: `layout: horizon wide my-extra`.
|
||||
|
||||
## Examples
|
||||
|
||||
Built-in template with overrides:
|
||||
````markdown
|
||||
```menu
|
||||
layout: horizon
|
||||
@@ -142,23 +201,25 @@ hover-text: #ffd700
|
||||
```
|
||||
````
|
||||
|
||||
### Different Fonts Per Link Type
|
||||
Custom class with overrides:
|
||||
````markdown
|
||||
```menu
|
||||
layout: default
|
||||
font: "Inter"
|
||||
internal-font: "Fira Code"
|
||||
external-font: "Georgia"
|
||||
file-font: "Arial"
|
||||
[[Code Notes]]
|
||||
[Articles](https://medium.com)
|
||||
[Local Files](file:///C:/Documents)
|
||||
class: my-toolbar
|
||||
text: var(--text-normal)
|
||||
hover-text: var(--text-accent)
|
||||
[[Inbox]]
|
||||
[Wiki](https://example.com)
|
||||
```
|
||||
````
|
||||
|
||||
## Notes
|
||||
|
||||
- Use either `layout:` or `class:` (both work the same)
|
||||
- File paths use `file://` protocol
|
||||
- Colors support hex, rgb, hsl, CSS variables, and gradients
|
||||
- Font names with spaces need quotes: `font: "Work Sans"`
|
||||
Minimal template focusing on text colors:
|
||||
````markdown
|
||||
```menu
|
||||
layout: minimal
|
||||
internal-text: var(--text-accent)
|
||||
external-text: var(--text-faint)
|
||||
file-text: var(--text-muted)
|
||||
[[Notes]]
|
||||
[Web](https://example.com)
|
||||
[Folder](file:///C:/Projects)
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user