âââââââ âââââââ ââââââ âââââââââââââââââââ âââââââ ââââââ âââ âââ âââ
âââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââââ âââ âââ
âââââââââââââââââââââââââââ âââ ââââââ âââââââââââ âââ âââ
âââââââ âââââââââââââââââââ âââ ââââââ âââââââââââ âââ âââ
âââ âââ ââââââ âââââââââââ âââ ââââââââââââââ ââââââââââââââââââââââ
âââ âââ ââââââ âââ âââââââ âââ âââ ââââââââââ ââââââââââââââââââââââ
ââââââââââ âââââââ ââââââ ââââââââââ ââââââââ
âââââââââââ âââââââââ ââââââ âââââââââââââââââââ
âââ âââ âââ âââ ââââââ âââââââââââââââââ
âââ âââ âââ âââââ ââââââ âââââââââââââââââ
âââââââââââââââââââââââââââââââââââââââââââââ âââââââââââ
âââââââââââââââ âââââââ ââââââ âââââââ âââ âââââââââââ
Book status
License
Contributing
Issues and pull requests are most welcome. Please detail issues as much as you can. Pull requests are simpler to work with when they are specific to a page or at most a section. The smaller the change the quicker it is to review and merge.
Please see the detailed contributing section of the book before raising an issue or pull request
practicalli/clojure-deps-edn GitHub repository contains the Clojure CLI user level configuration used in this guide and issues and pull requests can also be made there.
By submitting content ideas and corrections you are agreeing they can be used in this workshop under the Creative Commons Attribution ShareAlike 4.0 International license. Attribution will be detailed via GitHub contributors.
GitHub Actions
The Linter GitHub actions will run when a pull request is created, checking basic markdown syntax.
A review of the change will be carried out by the Practicalli team and the PR merged if the change is acceptable.
The Publish Website GitHub action will run when PR's are merged (or the Practicalli team cherry picks changes to the default branch).
GitBook Static Site Generator
GitBook open source tool is used to generate all the Practicalli books, as it provides a simple way to provide effective navigation across a guide or book with a large number of pages.
Install locally
GitBook can be installed locally to support larger pieced of content development. It provides a local server that should continually build the site when changes are saved.
GitBook requires node.js version 11 (or version 10, or 8). GitBook plugins will fail with node versions higher than 11.
Install GitBook using node package manager
npm install gitbook-cli -gFork the practicalli/clojure GitHub repository and clone that fork to your computer,
git clone https://github.com/<your-github-account>/clojure.git
Switch to the root directory of the cloned repository when complete.
Install the GitBook plugins used for this project (as defined in the book.json configuration)
cd clojure
gitbook installIf any plugins fail to install, ensure node version 11 (or 10) is being used
Run a local server to generate the website from the markdown content, which also listens for changes
gitbook serveGitbook plugins
GitBook has numerous community plugins to extend its functionality.
The following plugins are currently used for Practicalli books.
- anchor-headings-lambda
- callouts
- codeblock-disable-glossary
- disqus
- folding-chapters - fold navigation sections
- ga - Google analytics
- -glossary - disable default glossary
- -highlight - disable default highlight (prism)
- klipse - embed Klipse code evaluation in pages
- newtabs - in-page tab sections
- prism code block syntax highlighting (use jr0cket.css theme, added manually)
- sectionx-ex - in-page sections that can be collapsed (klipse doesn't work inside a section)
- -sharing - buttons to share on social media (default plugin disabled)
- splitter - movable vertical bar between navigation and content, remembers position
- terminull-light - fancy console - draws copy button on klipse elements
- theme-jr0cket - custom version of theme-code, removing numbering
- toggle-chapters - collapsed and expand navigation sections
- toolbar - add toolbar of links to GitHub, Chat, etc.
- youtubex - embed YouTube videos by id, rending responsively to page size
- wide-page - gitbook plugin to have a fluid page width instead of fixed