commit ff112713f932f9c6b79f3c525fdf13bc3993ab56 Author: Ben Cuan Date: Sun Jan 1 23:41:14 2023 +0000 initial commit: combine book with quartz diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..ed38cff --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +public/ +exampleSite/public/ +.DS_Store +.hugo_build.lock +themes \ No newline at end of file diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..12744dd --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "themes/hugo-book"] + path = themes/hugo-book + url = https://github.com/alex-shpak/hugo-book diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..92452b3 --- /dev/null +++ b/LICENSE @@ -0,0 +1,20 @@ +The MIT License (MIT) + +Copyright (c) 2022 Ben Cuan + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software is furnished to do so, +subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS +FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR +COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER +IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN +CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..50d542a --- /dev/null +++ b/Makefile @@ -0,0 +1,24 @@ +.DEFAULT_GOAL := serve + +help: ## Show all Makefile targets + @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}' + +update: ## Update Quartz to the latest version on Github + go install github.com/jackyzha0/hugo-obsidian@latest + @git remote show upstream || (echo "remote 'upstream' not present, setting 'upstream'" && git remote add upstream https://github.com/jackyzha0/quartz.git) + git fetch upstream + git log --oneline --decorate --graph ..upstream/hugo + git checkout -p upstream/hugo -- layouts .github Makefile assets/js assets/styles/base.scss assets/styles/darkmode.scss config.toml data + +update-force: ## Forcefully pull all changes and don't ask to patch + go install github.com/jackyzha0/hugo-obsidian@latest + @git remote show upstream || (echo "remote 'upstream' not present, setting 'upstream'" && git remote add upstream https://github.com/jackyzha0/quartz.git) + git fetch upstream + git checkout upstream/hugo -- layouts .github Makefile assets/js assets/styles/base.scss assets/styles/darkmode.scss config.toml data + +serve: ## Serve Quartz locally + hugo-obsidian -input=content -output=assets/indices -index -root=. + hugo server --enableGitInfo --minify --bind=$(or $(HUGO_BIND),0.0.0.0) --baseURL=$(or $(HUGO_BASEURL),http://localhost) --port=$(or $(HUGO_PORT),1313) --appendPort=$(or $(HUGO_APPENDPORT),true) + +docker: ## Serve locally using Docker + docker run -it --volume=$(shell pwd):/quartz -p 1313:1313 ghcr.io/jackyzha0/quartz:hugo diff --git a/README.md b/README.md new file mode 100644 index 0000000..02cad52 --- /dev/null +++ b/README.md @@ -0,0 +1,218 @@ +# Amethyst Hugo Theme + +[![Hugo](https://img.shields.io/badge/hugo-0.79-blue.svg)](https://gohugo.io) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) + +Amethyst combines the navigational features of [hugo-book](https://github.com/alex-shpak/hugo-book) with the Obsidian integrations of [quartz](https://github.com/jackyzha0/quartz) to provide a hassle-free place to store and host personal notes or documentation. + +Insert screenshot here + +## Features +- Most of the features of the original themes (Quartz and Book) +- Mobile-friendly +- Multi-language support +- Customizable +- Dark Mode +- LaTeX support +- Obsidian-style back/forward links and page previews +- Interactive graph view +- Tab cards for practice problems + +## Requirements + +- **Go 1.16 or higher**: [installation instructions](https://golang.org/doc/install) +- **Hugo 0.93 or higher:** [installation instructions](https://gohugo.io/getting-started/installing/) + - If installing on Ubuntu/Debian-based systems, this is a higher version than is available in apt at the time of writing. Install the extended version from the [releases page](https://github.com/gohugoio/hugo/releases) instead. +- **Hugo-obsidian:** Run `go install github.com/jackyzha0/hugo-obsidian@latest`. + - If you're getting a `command not found` error, [ensure that your PATH is configured properly so that binaries in the GOPATH can be executed](https://stackoverflow.com/questions/21001387/how-do-i-set-the-gopath-environment-variable-on-ubuntu-what-file-must-i-edit). + +## Installation + +### Install as git submodule +Navigate to your hugo project root and run: + +``` +git submodule add https://github.com/64bitpandas/amethyst themes/amethyst +``` + +Then run hugo (or set `theme = "amethyst"`/`theme: amethyst` in configuration file) + +``` +hugo server --minify --theme amethyst +``` + +### Install as hugo module + +You can also add this theme as a Hugo module instead of a git submodule. + +Start with initializing hugo modules, if not done yet: +``` +hugo mod init github.com/repo/path +``` + +Navigate to your hugo project root and add [module] section to your `config.toml`: + +```toml +[module] +[[module.imports]] +path = 'github.com/alex-shpak/hugo-book' +``` + +Then, to load/update the theme module and run hugo: + +```sh +hugo mod get -u +hugo server --minify +``` + +### Creating site from scratch + +Below is an example on how to create a new site from scratch: + +```sh +hugo new site mydocs; cd mydocs +git init +git submodule add https://github.com/alex-shpak/hugo-book themes/hugo-book +cp -R themes/hugo-book/exampleSite/content . +``` + +```sh +hugo server --minify --theme hugo-book +``` + +## Configuration + +### Site Configuration + +Most configuration can be done by creating a `config.yaml` file in the root directory and editing the parameters. You can start by copying the example [here](https://github.com/64bitpandas/amethyst/blob/main/config.yaml). + +Graph-specific configuration can be added to `data/graphConfig.yaml`. (Example [here](https://github.com/64bitpandas/amethyst/blob/main/data/graphConfig.yaml)) + + +### Multi-Language Support + +Theme supports Hugo's [multilingual mode](https://gohugo.io/content-management/multilingual/), just follow configuration guide there. You can also tweak search indexing configuration per language in `i18n` folder. + +### Page Configuration + +You can specify additional params in the front matter of individual pages: + +```toml +# Set type to 'docs' if you want to render page outside of configured section or if you render section other than 'docs' +type = 'docs' + +# Set page weight to re-arrange items in file-tree menu (if BookMenuBundle not set) +weight = 10 + +# (Optional) Set to 'true' to mark page as flat section in file-tree menu (if BookMenuBundle not set) +bookFlatSection = false + +# (Optional) Set to hide nested sections or pages at that level. Works only with file-tree menu mode +bookCollapseSection = true + +# (Optional) Set true to hide page or section from side menu (if BookMenuBundle not set) +bookHidden = false + +# (Optional) Set 'false' to hide ToC from page +bookToC = true + +# (Optional) If you have enabled BookComments for the site, you can disable it for specific pages. +bookComments = true + +# (Optional) Set to 'false' to exclude page from search index. +bookSearchExclude = true + +# (Optional) Set explicit href attribute for this page in a menu (if BookMenuBundle not set) +bookHref = '' +``` + +### Partials + +There are layout partials available for you to easily override components of the theme in `layouts/partials/`. + +In addition to this, there are several empty partials you can override to easily add/inject code. + +| Empty Partial | Placement | +| -------------------------------------------------- | ------------------------------------------- | +| `layouts/partials/docs/inject/head.html` | Before closing `` tag | +| `layouts/partials/docs/inject/body.html` | Before closing `` tag | +| `layouts/partials/docs/inject/footer.html` | After page footer content | +| `layouts/partials/docs/inject/menu-before.html` | At the beginning of `