https://github.com/harmoniqs/piccolodocstemplate.jl
https://github.com/harmoniqs/piccolodocstemplate.jl
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/harmoniqs/piccolodocstemplate.jl
- Owner: harmoniqs
- Created: 2025-08-06T01:05:44.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-02-09T04:57:20.000Z (4 months ago)
- Last Synced: 2026-02-09T10:52:38.991Z (4 months ago)
- Language: Julia
- Size: 20.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# PiccoloDocsTemplate
Simply
```
Pkg.add(url="https://github.com/harmoniqs/PiccoloDocsTemplate.jl", rev="v0.3.0")
Pkg.instantiate()
```
and then add a
```
using MyPackageHere
using PiccoloDocsTemplate
pages = [ ... ]
generate_docs( ... )
```
## usage notes
By default, `make_index=true`, which means the README.md for the package is used to create the index page (for Documenter, via `index.md`). Because of some rendering differences between github and documenter, sometimes we have annotate sections in the README so that our `index.md` file for Documenter is correct.
1. You can hide text from the README, which needs to be included into index.md via html comment blocks. Github will not render the content of these, our `generate_index` function strips out the content inside of the comment, and replaces that entire line with the content like so (view in editor to see text content):
```
Here's a sentence that will only be displayed on the Github README
Here's a sentence that will only be displayed on the Github README (and is just deleted from the docs pages)
Here's a sentence that get's displayed in both places
```
2. Code blocks with julia syntax highlighting *and* marked "example" will be included into our index.md as `@example` blocks, thus being run as example code blocks when building our documentation, and warning at documentation build that the block(s) fail.
(in README)
### example code
```julia example
1 + 1
```
(what gets generated in index.md, nothing at end suppresses output for index pages)
```@example
1 + 1
nothing # hide
```