-
Notifications
You must be signed in to change notification settings - Fork 1
/
core.cljc
136 lines (97 loc) · 3.61 KB
/
core.cljc
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
(ns cljdoc-exerciser.core
"Here we look at cljdoc features for APIs
Namespace docstrings **can** contain markdown.
And should support links repo [to articles](/doc/tests/md-features.md)
and inline repo images
![«test image 1 should appear»](/images/test-image-1.png)
Wikilinks work from namespace docstrings:
- a var local to this namespace [[exercise7]]
- a different namespace [[cljdoc-exerciser.ns2]]
- a var in a different namespace [[cljdoc-exerciser.ns2/whatever]]
Wikilink syntax [[that does not resolve to any var or ns]] is not converted to a link,
this includes any typos like [[cljdoc-exerciser.ns2/whatevs]] [[cljdoc-exorcisor.core]]")
(defn exercise1
"Will someone ever link to me?"
[d e f]
(* d e f))
(defn exercise2
"**A function docstring can contain CommonMark formatted text.**
**Lists**
1. one
2. two
- buckle
- my
- shoe
**Blockquotes**
> A quote
>> a nested quote
>>> a very nested quote
**Paragraphs**
If you want a paragraph to include a linebreak, \\
you can do that.
**Tables**
Tables are a CommonMark extension but supported by cljdoc
| Left | Centered | Right |
|----------|:-------------:|------:|
| lets | peanut butter | 100 |
| fill | and | 10 |
| this | pickles | 1 |
**Code blocks**
```clojure
(defn exercise
\"A docstring can contain CommonMark formatted text.\"
[]
(+ 4 5 6))
```
**Links**
An external link to [the CommonMark website](https://commonmark.org/).
A docstring can reference resources on GitHub.
You'll need to use a GitHub root relative link for this.
Root relative links start with `/`.
A root relative link has the following benefits:
- it will also work when users decide to download your cljdocs into an offline bundle
- does not specify project coords, making it GitHub fork friendly
Examples:
- [an imported article will be shown on cljdoc](/doc/tests/md-features.md)
- [another resource will link you to GitHub](/doc/tests/excluded.md)
- [specifying a relative link results in error link](doc/tests/excluded.md)
**Wikilinks**
Wikilinks are a cljdoc extension to CommonMark and allow you to link to API functions.
They only work in docstrings:
- a var local to this namespace [[exercise1]]
- a different namespace [[cljdoc-exerciser.ns2]]
- a var in a different namespace [[cljdoc-exerciser.ns2/whatever]]
Wikilink syntax [[that does not resolve to any var or ns]] is not converted to a link,
this includes any typos like [[cljdoc-exerciser.ns2/whatevs]] [[cljdoc-exorcisor.core]]"
[]
(+ 1 2 3))
(defn exercise3
"Linking to images might be of interest.
Specify your images as root relative (starting with a `/`):
![«my local test image should appear here»](/images/test-image-1.png \"my local test image text\")
Otherwise they will result in errored references:
![«alt image text»](../../images/test-image-1.png)
An external image should work fine too:
![«an external image should appear here»](https://dummyimage.com/300x100/000000/fff&text=an+external+image)"
[x y z])
(defn exercise4
"Using headings in a docstring might be ridiculous, but you can do it.
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
this is too much, I am heading home."
[a b c])
#?(:cljs
(defn exercise5
"This function is for ClojureScript only."
[j s]) )
#?(:clj
(defn exercise6
"This function is for Clojure only."
[j v m]))
(defn exercise7
"How does a docstring handle embedded html?
It is not <b>bold</b> enough to render it."
[])