Skip to content

Commit 8cf494f

Browse files
pbekpbek
committed
Add new markdown documentation, generated with MkDocs
1 parent 7315cf8 commit 8cf494f

29 files changed

+2430
-0
lines changed

‎.readthedocs.yml

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
version: 2
2+
3+
mkdocs:
4+
configuration: docs/mkdocs.yml
5+
6+
# Build docs in additional formats such as PDF and ePub
7+
formats: all
8+
9+
python:
10+
version: 3.7
11+
install:
12+
- requirements: docs/requirements.txt

‎docs/.dockerignore

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
site/

‎docs/.markdownlint.json

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"no-hard-tabs": false,
3+
"MD007": { "indent": 4 },
4+
"MD009": false,
5+
"MD013": false,
6+
"MD024": false,
7+
"MD026": false,
8+
"MD033": false,
9+
"MD034": false,
10+
"MD036": false,
11+
"MD046": false
12+
}

‎docs/Makefile

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
2+
#######
3+
# This Makefile contains all targets related to the documentation
4+
#######
5+
6+
DOCS_VERIFY_SKIP ?= false
7+
DOCS_LINT_SKIP ?= false
8+
9+
QOWNNOTES_DOCS_BUILD_IMAGE ?= qownnotes-docs
10+
QOWNNOTES_DOCS_CHECK_IMAGE ?= $(QOWNNOTES_DOCS_BUILD_IMAGE)-check
11+
12+
SITE_DIR := $(CURDIR)/site
13+
14+
DOCKER_RUN_DOC_PORT := 8000
15+
DOCKER_RUN_DOC_MOUNTS := -v $(CURDIR):/mkdocs
16+
DOCKER_RUN_DOC_OPTS := --rm $(DOCKER_RUN_DOC_MOUNTS) -p $(DOCKER_RUN_DOC_PORT):8000
17+
18+
# Default: generates the documentation into $(SITE_DIR)
19+
docs: docs-clean docs-image docs-lint docs-build docs-verify
20+
21+
# Writer Mode: build and serve docs on http://localhost:8000 with livereload
22+
docs-serve: docs-image
23+
docker run $(DOCKER_RUN_DOC_OPTS) $(QOWNNOTES_DOCS_BUILD_IMAGE) mkdocs serve
24+
25+
# Utilities Targets for each step
26+
docs-image:
27+
docker build -t $(QOWNNOTES_DOCS_BUILD_IMAGE) -f docs.Dockerfile ./
28+
29+
docs-build: docs-image
30+
docker run $(DOCKER_RUN_DOC_OPTS) $(QOWNNOTES_DOCS_BUILD_IMAGE) sh -c "mkdocs build \
31+
&& chown -R $(shell id -u):$(shell id -g) ./site"
32+
33+
docs-verify: docs-build
34+
@if [ "$(DOCS_VERIFY_SKIP)" != "true" ]; then \
35+
docker build -t $(QOWNNOTES_DOCS_CHECK_IMAGE) -f check.Dockerfile ./; \
36+
docker run --rm -v $(CURDIR):/app $(QOWNNOTES_DOCS_CHECK_IMAGE) /verify.sh; \
37+
else \
38+
echo "DOCS_VERIFY_SKIP is true: no verification done."; \
39+
fi
40+
41+
docs-lint:
42+
@if [ "$(DOCS_LINT_SKIP)" != "true" ]; then \
43+
docker build -t $(QOWNNOTES_DOCS_CHECK_IMAGE) -f check.Dockerfile ./ && \
44+
docker run --rm -v $(CURDIR):/app $(QOWNNOTES_DOCS_CHECK_IMAGE) /lint.sh; \
45+
else \
46+
echo "DOCS_LINT_SKIP is true: no linting done."; \
47+
fi
48+
49+
docs-clean:
50+
rm -rf $(SITE_DIR)
51+
52+
.PHONY: all docs-verify docs docs-clean docs-build docs-lint

‎docs/README.md

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# QOwnNotes Documentation
2+
3+
## Tooling
4+
5+
| Tool | Documentation | Sources |
6+
|-------------------|-------------------------------------|-----------------------------------|
7+
| mkdocs | [documentation][mkdocs] | [Sources][mkdocs-src] |
8+
| mkdocs-material | [documentation][mkdocs-material] | [Sources][mkdocs-material-src] |
9+
| pymdown-extensions| [documentation][pymdown-extensions] | [Sources][pymdown-extensions-src] |
10+
11+
12+
[mkdocs]: https://www.mkdocs.org "Mkdocs"
13+
[mkdocs-src]: https://github.com/mkdocs/mkdocs "Mkdocs - Sources"
14+
15+
[mkdocs-material]: https://squidfunk.github.io/mkdocs-material/ "Material for MkDocs"
16+
[mkdocs-material-src]: https://github.com/squidfunk/mkdocs-material "Material for MkDocs - Sources"
17+
18+
[pymdown-extensions]: https://facelessuser.github.io/pymdown-extensions/extensions "PyMdown Extensions"
19+
[pymdown-extensions-src]: https://github.com/facelessuser/pymdown-extensions "PyMdown Extensions - Sources"

‎docs/check.Dockerfile

+40
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
2+
FROM alpine:3.10 as alpine
3+
4+
RUN apk --no-cache --no-progress add \
5+
libcurl \
6+
ruby \
7+
ruby-bigdecimal \
8+
ruby-etc \
9+
ruby-ffi \
10+
ruby-json \
11+
ruby-nokogiri
12+
RUN gem install html-proofer --version 3.13.0 --no-document -- --use-system-libraries
13+
14+
# After Ruby, some NodeJS YAY!
15+
RUN apk --no-cache --no-progress add \
16+
git \
17+
nodejs \
18+
npm
19+
20+
# To handle 'not get uid/gid'
21+
RUN npm config set unsafe-perm true
22+
23+
RUN npm install --global \
24+
[email protected] \
25+
[email protected]
26+
27+
# Finally the shell tools we need for later
28+
# tini helps to terminate properly all the parallelized tasks when sending CTRL-C
29+
RUN apk --no-cache --no-progress add \
30+
ca-certificates \
31+
curl \
32+
tini
33+
34+
COPY ./scripts/verify.sh /verify.sh
35+
COPY ./scripts/lint.sh /lint.sh
36+
37+
WORKDIR /app
38+
VOLUME ["/tmp","/app"]
39+
40+
ENTRYPOINT ["/sbin/tini","-g","sh"]

‎docs/content/CNAME

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
docs.qownnotes.org

‎docs/content/assets/img/qownnotes.icon.png

5.98 KB
Loading

‎docs/content/assets/img/qownnotes.logo.png

57 KB
Loading

‎docs/content/assets/img/qownnotes.screenshot.png

237 KB
Loading

‎docs/content/assets/js/extra.js

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
/* Highlight */
2+
(function(hljs) {
3+
hljs.initHighlightingOnLoad();
4+
})(hljs);

‎docs/content/assets/js/hljs/LICENSE

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
Copyright (c) 2006, Ivan Sagalaev
2+
All rights reserved.
3+
Redistribution and use in source and binary forms, with or without
4+
modification, are permitted provided that the following conditions are met:
5+
6+
* Redistributions of source code must retain the above copyright
7+
notice, this list of conditions and the following disclaimer.
8+
* Redistributions in binary form must reproduce the above copyright
9+
notice, this list of conditions and the following disclaimer in the
10+
documentation and/or other materials provided with the distribution.
11+
* Neither the name of highlight.js nor the names of its contributors
12+
may be used to endorse or promote products derived from this software
13+
without specific prior written permission.
14+
15+
THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
16+
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
17+
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
18+
DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
19+
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
20+
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
21+
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
22+
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23+
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
24+
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

‎docs/content/assets/js/hljs/highlight.pack.js

+2
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/content/assets/styles/atom-one-light.css

+96
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
/*
2+
3+
Atom One Light by Daniel Gamage
4+
Original One Light Syntax theme from https://github.com/atom/one-light-syntax
5+
6+
base: #fafafa
7+
mono-1: #383a42
8+
mono-2: #686b77
9+
mono-3: #a0a1a7
10+
hue-1: #0184bb
11+
hue-2: #4078f2
12+
hue-3: #a626a4
13+
hue-4: #50a14f
14+
hue-5: #e45649
15+
hue-5-2: #c91243
16+
hue-6: #986801
17+
hue-6-2: #c18401
18+
19+
*/
20+
21+
.hljs {
22+
display: block;
23+
overflow-x: auto;
24+
padding: 0.5em;
25+
color: #383a42;
26+
background: #fafafa;
27+
}
28+
29+
.hljs-comment,
30+
.hljs-quote {
31+
color: #a0a1a7;
32+
font-style: italic;
33+
}
34+
35+
.hljs-doctag,
36+
.hljs-keyword,
37+
.hljs-formula {
38+
color: #a626a4;
39+
}
40+
41+
.hljs-section,
42+
.hljs-name,
43+
.hljs-selector-tag,
44+
.hljs-deletion,
45+
.hljs-subst {
46+
color: #e45649;
47+
}
48+
49+
.hljs-literal {
50+
color: #0184bb;
51+
}
52+
53+
.hljs-string,
54+
.hljs-regexp,
55+
.hljs-addition,
56+
.hljs-attribute,
57+
.hljs-meta-string {
58+
color: #50a14f;
59+
}
60+
61+
.hljs-built_in,
62+
.hljs-class .hljs-title {
63+
color: #c18401;
64+
}
65+
66+
.hljs-attr,
67+
.hljs-variable,
68+
.hljs-template-variable,
69+
.hljs-type,
70+
.hljs-selector-class,
71+
.hljs-selector-attr,
72+
.hljs-selector-pseudo,
73+
.hljs-number {
74+
color: #986801;
75+
}
76+
77+
.hljs-symbol,
78+
.hljs-bullet,
79+
.hljs-link,
80+
.hljs-meta,
81+
.hljs-selector-id,
82+
.hljs-title {
83+
color: #4078f2;
84+
}
85+
86+
.hljs-emphasis {
87+
font-style: italic;
88+
}
89+
90+
.hljs-strong {
91+
font-weight: bold;
92+
}
93+
94+
.hljs-link {
95+
text-decoration: underline;
96+
}

‎docs/content/assets/styles/extra.css

+64
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
@import url('https://fonts.googleapis.com/css?family=Noto+Sans|Noto+Serif');
2+
3+
.md-logo img {
4+
background-color: white;
5+
border-radius: 50%;
6+
width: 30px;
7+
height: 30px;
8+
border: solid 1px white;
9+
}
10+
11+
/* Fix for Chrome */
12+
.md-typeset__table td code {
13+
word-break: unset;
14+
}
15+
16+
.md-typeset__table tr :nth-child(1) {
17+
word-wrap: break-word;
18+
max-width: 30em;
19+
}
20+
21+
body {
22+
font-family: 'Noto Sans', sans-serif;
23+
}
24+
25+
h1 {
26+
font-weight: bold !important;
27+
color: rgba(0,0,0,.9) !important;
28+
}
29+
30+
h2 {
31+
font-weight: bold !important;
32+
}
33+
34+
h3 {
35+
font-weight: bold !important;
36+
}
37+
38+
.md-typeset h5 {
39+
text-transform: none;
40+
}
41+
42+
figcaption {
43+
text-align: center;
44+
font-size: 0.8em;
45+
font-style: italic;
46+
color: #8D909F;
47+
}
48+
49+
p.subtitle {
50+
color: rgba(0,0,0,.54);
51+
padding-top: 0;
52+
margin-top: -2em;
53+
font-weight: bold;
54+
font-size: 1.25em;
55+
}
56+
57+
.markdown-body .task-list-item {
58+
list-style-type: none !important;
59+
}
60+
61+
.markdown-body .task-list-item input[type="checkbox"] {
62+
margin: 0 4px 0.25em -20px;
63+
vertical-align: middle;
64+
}

0 commit comments

Comments
 (0)