Added README

This commit is contained in:
David Thurstenson 2021-11-21 16:47:03 -06:00
parent ad88e5c998
commit f315d4598b
2 changed files with 88 additions and 0 deletions

3
.gitignore vendored
View File

@ -18,3 +18,6 @@
# Static directory # Static directory
!static/ !static/
# README
!README.md

85
README.md Normal file
View File

@ -0,0 +1,85 @@
# Thurstylark's wiki
## Requirements
- Base
- hugo
- Optional (required for `tlwiki` management script)
- git
- python3
- rsync
## Usage
### Environment Setup
#### Using `tlwiki` script
1. Ensure these additional requirements are met:
2. Create `tlwiki-conf.yaml` using `tlwiki-conf.yaml.ex` as a template
3. Run `./tlwiki updeps` to pull in the latest version of all git submodules
#### Using individual commands
1. Initialize all git submodules
```
git submodule update --init --recursive
```
### Deploy
#### Using `tlwiki` script
1. Ensure the values for `deployID.user`, `deployID.host`, and `deployID.dir` are correct
- For best results, use rsync with a non-interactive authentication method such as ssh key pairs
2. Run `./tlwiki deploy`
#### Using individual commands
1. Run `hugo` to build the site
2. Copy the contents of `public/` to your web server's document root
## Hacking
### Automatically run `./tlwiki deploy` on `git push`
Create a symlink named `.git/hooks/pre-push` with `tlwiki` as its target:
```
ln -s .git/hooks/pre-push ../../tlwiki
```
`tlwiki` will help manage this symlink in the future (See: [#1](https://git.thurstylark.com/thurstylark/tlwiki/issues/1))
### Serve the site locally for testing
```
hugo server
```
More info: https://gohugo.io/commands/hugo_server/
## `tlwiki-config.yaml` Configuration Options
| Path | Type | Default | Description |
|-----------------|--------|---------|----------------------------------------------------------|
| deployID.user | string | <none> | rsync username (`USER` in `USER@HOST:DIR`) |
| deployID.host | string | <none> | rsync hostname (`HOST` in `USER@HOST:DIR`) |
| deployID.dir | string | <none> | rsync target remote directory (`DIR` in `USER@HOST:DIR`) |
| repo.URL | string | <none> | Unused |
| repo.branch | string | <none> | Unused |
| repo.remoteName | string | <none> | Unused |