a pretty lit content authoring system
Home Page: https://booklit.page
License: MIT License
Booklit is a tool for building static websites from semantic documents.
grab the latest release, or build from source:
go get github.com/vito/booklit/cmd/booklit
go install github.com/vito/booklit/cmd/booklitbooklit -i foo.lit -o ./outclone this repo and build the Booklit website:
./scripts/build-docsthen browse the generated docs from ./docs/index.html.
alternatively, run the docs in server mode:
./scripts/build-docs -s 3000...and then browse to localhost:3000
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
Should this be opt-in? Fetching all the links all the time is probably expensive.
Also probably wise to do a HEAD request first so we don't end up downloading large assets.
In the Getting Started:
# add booklit to go.mod and install CLI
go get github.com/vito/booklit/cmd/booklit
Installs the CLI, but using commands after this step without adding GOPATH/bin to the $PATH doesn't work.
This may be common knowledge for more experienced users 🙂 but for Go n00bs like myself, it would be a nice UX to have this step included in the docs:
export PATH=$(go env GOPATH)/bin:$PATH
This is a question more than a bug report, but would the windows binary still work with the addition of "plugin" package?
Minimally, I wouldn't expect the "--plugin" flag to work on windows, right?
Just food for thought. I almost opened a PR to remove the windows binary creation, but I decided against it as I actually don't know how the binary compilation step works for these go packages and if booklit is no longer windows compatible at all, just partially, or completely unimpaired.
Thanks!
Bass's docs are getting pretty slow to build because they run a lot of example code. It would be nice to know which examples are the slowest so I can speed things up. There's probably a lot of low-hanging fruit.
quality-of-life improvement for plugin functions which take numeric args like \foos{5}:
func (plug MyPlugin) Foos(count int) booklit.Content {
// ...
}instead of
func (plug MyPlugin) Foos(countStr string) (booklit.Content, error) {
count, err := strconv.Atoi(countStr)
if err != nil {
return nil, err
}
}use case: being able to configure the number of dynamically fetched entries to show without having to recompile the plugin with a magic const value.
I've tried a steps from README:
$ go get github.com/vito/booklit/cmd/booklit
go: downloading github.com/go-bindata/go-bindata v3.1.2+incompatible
go: downloading github.com/mna/pigeon v1.0.1-0.20200224192238-18953b277063
go: downloading golang.org/x/tools v0.0.0-20200505023115-26f46d2f7ef8
$ git clone https://github.com/vito/booklit.git
Клонирование в «booklit»
…
$ cd booklit
booklit$ booklit \
> -i docs/lit/index.lit \
> -o docs \
> --html-templates docs/lit/html \
> --plugin github.com/vito/booklit/docs/go \
> --plugin github.com/vito/booklit/chroma/plugin
INFO[0000] rendering rendered=docs/index.html section=docs/lit/index.lit
template: page.tmpl:8:10: executing "page.tmpl" at <render>: error calling render: template 'splash.tmpl' not found
Am I doing something wrong?
I like the abstraction slot !
First thing that comes to mind it building a web based playground for it.
Essentially all that means is to show the abstract syntax on the left and the output on the right.
The directory structure can be on the very left
When attempting to use booklit to build Concourse locally, I get the following error:
$ go get github.com/vito/booklit/cmd/booklit
$ pwd
/Users/pilot/workspace/concourse/built-docs
$ ls
README.md Staticfile css favicon.ico fonts html images js lit manifest.yml scripts src
$ ./scripts/build
# concourse-lit/community
src/concourse-lit/community/plugin.go:6: undefined: booklit.PluginFactoryFunc
# concourse-lit/resources-table
src/concourse-lit/resources-table/plugin.go:6: undefined: booklit.PluginFactoryFunc
# concourse-lit/splash
src/concourse-lit/splash/plugin.go:10: undefined: booklit.PluginFactoryFunc
# concourse-lit/docs
src/concourse-lit/docs/plugin.go:16: undefined: booklit.PluginFactoryFunc
exit status 2
https://booklit.page/baselit.html#aux this is a deep-link but nothing links to it
code snippets should auto-link, including the snippet that link goes to
currently flags like --html-templates and --plugin have to be passed on every command. maybe these could be in a config file instead? then we wouldn't need to keep writing scripts like scripts/build-docs.
counter-argument: writing a script already works and is almost the same amount of work
counter-counter argument: it's a little more awkward to write docs saying 'write a script' vs 'put this in your config'
could help alleviate fears of tying your content to Booklit forever - just convert it once and maintain the Markdown content directly from then on
This is handy for sections whose sub-sections aren't really relevant for higher-level navigation, i.e. the "What & Why" sub-sections on the main site.
put these somewhere on the website:
getting errors like this when adding --plugin github.com/vito/booklit/chroma/plugin:
❯ ./scripts/build -s 3001
INFO[0000] plugin registered plugin=baselit
../../../go/pkg/mod/github.com/vito/[email protected]/chroma/booklit_lexer.go:4:2: missing go.sum entry for module providing package github.com/alecthomas/chroma; to add:
go mod download github.com/alecthomas/chroma
../../../go/pkg/mod/github.com/vito/[email protected]/chroma/plugin.go:26:2: missing go.sum entry for module providing package github.com/alecthomas/chroma/formatters/html; to add:
go mod download github.com/alecthomas/chroma
../../../go/pkg/mod/github.com/vito/[email protected]/chroma/booklit_lexer.go:5:2: missing go.sum entry for module providing package github.com/alecthomas/chroma/lexers; to add:
go mod download github.com/alecthomas/chroma
../../../go/pkg/mod/github.com/vito/[email protected]/chroma/plugin.go:28:2: missing go.sum entry for module providing package github.com/alecthomas/chroma/styles; to add:
go mod download github.com/alecthomas/chroma
build failed: exit status 1
maybe --plugin can automatically add things to go.mod? unfortunately go mod tidy will clean that out. maybe there's some way to flag it? 🤔
maybe plugins should be enabled with a .go file that underscore-imports them?
would be pretty nice to have auto-completion for \ when writing .lit files
Is there any i18n or l10n support already?
Inline URLs tend to make the content flow awkwardly and force dramatic word wrapping. It'd be cool if I could write like this:
Foo \link{Bar}, fizz buzz baz.
...
Check out \link{Bar}!
\set-link{Bar}{https://example.com}Additional thoughts:
at the risk of being too fancy, it'd be nice to be able to write just [foo] like with Markdown.
another way to do this could be through partials:
\set-partial{Bar}{\link{Bar}{https://example.com}}
Foo \partial{Bar}, fizz buzz baz.... but that feels a bit too much like programming and not enough like 'writing what you mean'. (also \partial isn't a thing.)
copyright, etc
woops
nested section doesn't have FilePath, so annotating error location fails
this broke with interspersing. maybe a precedence issue? or maybe that never supported "sentence" form?
This is nice for omitting content from tag displays, e.g. \title{Concourse\aux{: CI that scales with your project.}}.
only way to know a plugin's name after importing is to guess - which is usually fine, but we could log something too
the documentation should explain the dependency on yarn
$ make
yarn run lessc less/docs.less docs/css/booklit.css
make: yarn: Command not found
make: *** [Makefile:12: docs/css/booklit.css] Error 127
currently go.sum is 241 lines:
https://github.com/vito/booklit/blob/master/go.sum
where a similar project is about half that:
maybe related to !. - seems to result in a nil, nil return value from parsing
A lot of these APIs are meant to be used by plugins, so godoc should be a high priority.
this is currently overridden at build time - perhaps it should be bumped in code as well?
Hi, I like to use footnotes on my pages. I wrote a very simple plugin that accomplishes this by adding arguments to a call of \footnote to a package global slice and rendering it when \footnotemark is called. This is probably not the best way to do it.
Do you think a feature like this should be added to baselit?
https://vito.github.io/docs results in a 404
When quickly jotting down notes, I had a document like this:
\title{Foo}
\title{Bar}
I expected to be able to navigate to foo.html, but it returned 404 because the title was overridden to Bar, resulting in bar.html.
This is pretty obviously an error (the second \title should be in its own \section) so it should be caught early to make troubleshooting easier.
We are using tools to validate that links in our site.
The link checker keeps returning that anchor links (#) are invalid.
After investigation, we found that the name attribute was being used for the anchors.
The name attribute is obsolete in HTML5 having been replaced with id behavior.
The HTML generated has a doctype for HTML5.
Would you accept a PR to be HTML5 compliant?
Getting error: failed to load plugin 'github.com/vito/booklit/booklitdoc': plugin: not implemented
Reproduce with:
git clone [email protected]:vito/booklit.git
cd booklit
booklit \
-i ./docs/lit/index.lit \
-o ./docs \
--html-templates docs/lit/html \
--plugin github.com/vito/booklit/booklitdoc
go env:
GOARCH="amd64"
GOBIN=""
GOCACHE="/Users/yuriikrevnyi/Library/Caches/go-build"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="darwin"
GOOS="darwin"
GOPATH="/Users/yuriikrevnyi/go"
GOPROXY=""
GORACE=""
GOROOT="/usr/local/Cellar/go/1.11.2/libexec"
GOTMPDIR=""
GOTOOLDIR="/usr/local/Cellar/go/1.11.2/libexec/pkg/tool/darwin_amd64"
GCCGO="gccgo"
CC="clang"
CXX="clang++"
CGO_ENABLED="1"
GOMOD="/Users/yuriikrevnyi/code/tmp/booklit/go.mod"
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -fdebug-prefix-map=/var/folders/n1/1fsc4x552wq69f8z3pz1ykqw0000gn/T/go-build369202601=/tmp/go-build -gno-record-gcc-switches -fno-common"
❯ booklit --help
INFO[0000] plugin registered plugin=base
Usage:
booklit [OPTIONS]
Application Options:
-v, --version Print the version of Boooklit and exit.
-i, --in= Input .lit file to load.
-o, --out= Directory into which sections will be rendered.
--section-tag= Section tag to render.
--section-path= Section path to load and render with --in as its parent.
--save-search-index Save a search index JSON file in the destination.
-s, --serve= Start an HTTP server on the given port.
-p, --plugin= Package to import, providing a plugin.
-d, --debug Log at debug level.
--allow-broken-references Replace broken references with a bogus tag.
HTML Rendering Engine:
--html-templates= Directory containing .tmpl files to load.
Text Rendering Engine:
--text-file-extension= File extension to use for generated files.
--text-templates= Directory containing .tmpl files to load.
Help Options:
-h, --help Show this help message
Usage:
booklit [OPTIONS]
Application Options:
-v, --version Print the version of Boooklit and exit.
-i, --in= Input .lit file to load.
-o, --out= Directory into which sections will be rendered.
--section-tag= Section tag to render.
--section-path= Section path to load and render with --in as its parent.
--save-search-index Save a search index JSON file in the destination.
-s, --serve= Start an HTTP server on the given port.
-p, --plugin= Package to import, providing a plugin.
-d, --debug Log at debug level.
--allow-broken-references Replace broken references with a bogus tag.
HTML Rendering Engine:
--html-templates= Directory containing .tmpl files to load.
Text Rendering Engine:
--text-file-extension= File extension to use for generated files.
--text-templates= Directory containing .tmpl files to load.
Help Options:
-h, --help Show this help message
this would make it a lot easier to clean up cruft left over from docs refactors/restructures
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.