Skip to content

Commit a147697

Browse files
claremacraeautoniaAnnaKornfeldSimpsonsailKiteV
authored
docs: Add "How to style backlinks" guide to "How Tos" section (#840)
* chore: Set attachment and new file location in Tasks-Demo vault * chore: Obsidian added "enabledCssSnippets" to appearance.json * sample vault: Add CSS snippets for customising backlinks * docs: Add screenshots showing customising of backlinks * docs: Add 'How to style backlinks' guide Using CSS snippets supplied by @autonia and @AnnaKornfeldSimpson Co-Authored-By: David Phillips <1128613+autonia@users.noreply.github.com> Co-Authored-By: Anna Kornfeld Simpson <AnnaKornfeldSimpson@users.noreply.github.com> * docs: Switch to fenced code blocks, to style CSS * docs: Remove need for an internet connection for icon With thanks to author @sailKiteV in GitHub for help in encoding the icon, and making this replace the original text completely. Co-Authored-By: sailKiteV <75286796+sailKiteV@users.noreply.github.com> * docs: Convert all links in new page to use 'gh-pages' branch * docs: Tidy up new images: make them consistent size Co-authored-by: David Phillips <1128613+autonia@users.noreply.github.com> Co-authored-by: Anna Kornfeld Simpson <AnnaKornfeldSimpson@users.noreply.github.com> Co-authored-by: sailKiteV <75286796+sailKiteV@users.noreply.github.com>
1 parent 3bbe9d5 commit a147697

12 files changed

+148
-4
lines changed

‎.markdownlint.jsonc

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
{
22
"MD013": false, // Ignore the line length rule.
33
"MD025": false, // Allow the title in the front matter and markdown heading one to match.
4-
"MD033": false // Allow Inline HTML.
4+
"MD033": false, // Allow Inline HTML.
5+
"MD046": false // Allow fenced code blocks, for syntax hughlighting.
56
}

‎docs/advanced/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
layout: default
33
title: Advanced
4-
nav_order: 6
4+
nav_order: 7
55
has_children: true
66
---
77

‎docs/how-to/index.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
layout: default
3+
title: How Tos
4+
nav_order: 6
5+
has_children: true
6+
---
7+
8+
# How Tos
9+
10+
{: .no_toc }
11+
12+
These How-to guides take you through the steps required to solve real-world problems with Tasks.

‎docs/how-to/style-backlinks.md

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
layout: default
3+
title: How to style backlinks
4+
nav_order: 2
5+
parent: How Tos
6+
---
7+
8+
# How to style backlinks
9+
10+
{: .no_toc }
11+
12+
<details open markdown="block">
13+
<summary>
14+
Table of contents
15+
</summary>
16+
{: .text-delta }
17+
1. TOC
18+
{:toc}
19+
</details>
20+
21+
---
22+
23+
## Motivation and assumptions
24+
25+
In Tasks results, by default each task is displayed with its filename,
26+
and the name of the previous heading, for example `(ACME > Steps to world domination)`.
27+
This is called a **backlink**.
28+
29+
If you don't like how backlinks look, this guide shows how you can modify their appearance.
30+
31+
We assume that you know how to [use CSS snippets in Obsidian](https://help.obsidian.md/How+to/Add+custom+styles#Use+Themes+and+or+CSS+snippets).
32+
33+
## Default backlink style
34+
35+
Here is an example task block that does not hide any components of the output: sometimes you want to see all the information in each task.
36+
37+
```tasks
38+
not done
39+
description includes trash
40+
```
41+
42+
This screenshot shows what this might look like, with some sample data:
43+
44+
![Tasks with vanilla backlink styles](https://github.com/obsidian-tasks-group/obsidian-tasks/raw/gh-pages/resources/screenshots/backlinks-default-style.png)
45+
46+
Notice that the backlinks (the blue file and heading names) can quite dominate the results, visually.
47+
48+
## Built-in options
49+
50+
We could use `hide backlink`, but then we would lose the ability to navigate to the source file.
51+
52+
We could also use `short mode`, which would replace the backlink text with an icon, but this would hide all the other properties of the task, such as due date and recurrence.
53+
54+
## Using CSS to de-emphasize the backlinks
55+
56+
We can de-emphasize the text in the backlinks, with [this CSS snippet](https://github.com/obsidian-tasks-group/obsidian-tasks/blob/gh-pages/resources/sample_vaults/Tasks-Demo/.obsidian/snippets/tasks-plugin-backlinks-small-grey.css):
57+
58+
```css
59+
/* By David Phillips (autonia) https://github.com/autonia
60+
From https://github.com/obsidian-tasks-group/obsidian-tasks/discussions/622#discussioncomment-2649299
61+
*/
62+
.tasks-backlink {
63+
font-size: 0.7em;
64+
opacity: 0.6;
65+
filter: grayscale(60%);
66+
}
67+
```
68+
69+
Which gives us this result:
70+
71+
![Tasks with small grey backlinks](https://github.com/obsidian-tasks-group/obsidian-tasks/raw/gh-pages/resources/screenshots/backlinks-snippet-tasks-plugin-backlinks-small-grey.png)
72+
73+
## Using CSS to replace the backlinks with icons
74+
75+
Or we can replace the backlink text with an icon, with [this CSS snippet](https://github.com/obsidian-tasks-group/obsidian-tasks/blob/gh-pages/resources/sample_vaults/Tasks-Demo/.obsidian/snippets/tasks-plugin-backlinks-icon.css):
76+
77+
```css
78+
/* By Anna Kornfeld Simpson (@AnnaKornfeldSimpson) https://github.com/AnnaKornfeldSimpson
79+
From https://github.com/obsidian-tasks-group/obsidian-tasks/discussions/834#discussioncomment-3028600
80+
81+
Then converted to embed the icon inside this .css file, to remove the need
82+
for an internet connection, as follows:
83+
1. Link icon downloaded from https://twemoji.twitter.com
84+
https://github.com/twitter/twemoji/blob/master/assets/svg/1f517.svg
85+
licensed under the CC-BY 4.0
86+
2. SVG encoded for embedding here with https://yoksel.github.io/url-encoder/
87+
*/
88+
li.plugin-tasks-list-item > span.tasks-backlink > a {
89+
content: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 36 36'%3E%3Cpath fill='%238899A6' d='M15 9l6-6s6-6 12 0 0 12 0 12l-8 8s-6 6-12 0c-1.125-1.125-1.822-2.62-1.822-2.62l3.353-3.348S14.396 18.396 16 20c0 0 3 3 6 0l8-8s3-3 0-6-6 0-6 0l-3.729 3.729s-1.854-1.521-5.646-.354L15 9z'/%3E%3Cpath fill='%238899A6' d='M20.845 27l-6 6s-6 6-12 0 0-12 0-12l8-8s6-6 12 0c1.125 1.125 1.822 2.62 1.822 2.62l-3.354 3.349s.135-1.365-1.469-2.969c0 0-3-3-6 0l-8 8s-3 3 0 6 6 0 6 0l3.729-3.729s1.854 1.521 5.646.354l-.374.375z'/%3E%3C/svg%3E");
90+
height: .9em;
91+
}
92+
```
93+
94+
Which gives us this result:
95+
96+
![Tasks with icons for backlink](https://github.com/obsidian-tasks-group/obsidian-tasks/raw/gh-pages/resources/screenshots/backlinks-snippet-tasks-plugin-backlinks-icon.png)

‎resources/sample_vaults/Tasks-Demo/.obsidian/app.json

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,7 @@
22
"legacyEditor": false,
33
"livePreview": true,
44
"useTab": false,
5-
"readableLineLength": false
5+
"readableLineLength": false,
6+
"newFileLocation": "current",
7+
"attachmentFolderPath": "./"
68
}

‎resources/sample_vaults/Tasks-Demo/.obsidian/appearance.json

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
11
{
2-
"theme": "moonstone"
2+
"theme": "moonstone",
3+
"enabledCssSnippets": []
34
}

‎resources/sample_vaults/Tasks-Demo/.obsidian/snippets/tasks-plugin-backlinks-icon.css

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
/* By Anna Kornfeld Simpson (@AnnaKornfeldSimpson) https://github.com/AnnaKornfeldSimpson
2+
From https://github.com/obsidian-tasks-group/obsidian-tasks/discussions/834#discussioncomment-3028600
3+
4+
Then converted to embed the icon inside this .css file, to remove the need
5+
for an internet connection, as follows:
6+
1. Link icon downloaded from https://twemoji.twitter.com
7+
https://github.com/twitter/twemoji/blob/master/assets/svg/1f517.svg
8+
licensed under the CC-BY 4.0
9+
2. SVG encoded for embedding here with https://yoksel.github.io/url-encoder/
10+
*/
11+
li.plugin-tasks-list-item > span.tasks-backlink > a {
12+
content: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 36 36'%3E%3Cpath fill='%238899A6' d='M15 9l6-6s6-6 12 0 0 12 0 12l-8 8s-6 6-12 0c-1.125-1.125-1.822-2.62-1.822-2.62l3.353-3.348S14.396 18.396 16 20c0 0 3 3 6 0l8-8s3-3 0-6-6 0-6 0l-3.729 3.729s-1.854-1.521-5.646-.354L15 9z'/%3E%3Cpath fill='%238899A6' d='M20.845 27l-6 6s-6 6-12 0 0-12 0-12l8-8s6-6 12 0c1.125 1.125 1.822 2.62 1.822 2.62l-3.354 3.349s.135-1.365-1.469-2.969c0 0-3-3-6 0l-8 8s-3 3 0 6 6 0 6 0l3.729-3.729s1.854 1.521 5.646.354l-.374.375z'/%3E%3C/svg%3E");
13+
height: .9em;
14+
}

‎resources/sample_vaults/Tasks-Demo/.obsidian/snippets/tasks-plugin-backlinks-small-grey.css

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
/* By David Phillips (autonia) https://github.com/autonia
2+
From https://github.com/obsidian-tasks-group/obsidian-tasks/discussions/622#discussioncomment-2649299
3+
*/
4+
.tasks-backlink {
5+
font-size: 0.7em;
6+
opacity: 0.6;
7+
filter: grayscale(60%);
8+
}

‎resources/sample_vaults/Tasks-Demo/Styling/Styling the Backlinks.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Styling the Backlinks
2+
3+
Here is an example task block that does not hide any components of the output.
4+
5+
It shows that the the backlink (the file and heading names) can quite dominate the results.
6+
7+
```tasks
8+
not done
9+
description includes trash
10+
```

‎resources/screenshots/backlinks-default-style.png

43.2 KB
Loading

0 commit comments

Comments
 (0)