Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/aaranxu/adidoks
AdiDoks is a mordern documentation theme, which is a port of the Hugo theme Doks for Zola.
https://github.com/aaranxu/adidoks
Last synced: 13 days ago
JSON representation
AdiDoks is a mordern documentation theme, which is a port of the Hugo theme Doks for Zola.
- Host: GitHub
- URL: https://github.com/aaranxu/adidoks
- Owner: aaranxu
- License: mit
- Created: 2021-05-03T01:41:30.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-06-09T08:08:16.000Z (5 months ago)
- Last Synced: 2024-08-01T22:58:17.832Z (3 months ago)
- Language: SCSS
- Homepage: https://adidoks.org
- Size: 1.34 MB
- Stars: 223
- Watchers: 6
- Forks: 81
- Open Issues: 41
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Zola Theme AdiDoks
AdiDoks is a modern documentation theme, which is a port of the Hugo
theme [Doks](https://github.com/h-enk/doks) for Zola.
## Demo
[Live Preview](https://adidoks.netlify.app/).
## Requirements
Before using the theme, you need to install the [Zola](https://www.getzola.org/documentation/getting-started/installation/) ≥ 0.15.0.
## Quick Start
```bash
git clone https://github.com/aaranxu/adidoks.git
cd adidoks
zola serve
# open http://127.0.0.1:1111/ in the browser
```
Read more from [the document of the AdiDoks](https://adidoks.org/docs/getting-started/introduction/).
## Installation
Just earlier we showed you how to run the theme directly. Now we start to
install the theme in an existing site step by step.
### Step 1: Create a new zola site
```bash
zola init mysite
```
### Step 2: Install AdiDoks
Download this theme to your themes directory:
```bash
cd mysite/themes
git clone https://github.com/aaranxu/adidoks.git
```
Or install as a submodule:
```bash
cd mysite
git init # if your project is a git repository already, ignore this command
git submodule add https://github.com/aaranxu/adidoks.git themes/adidoks
```
### Step 3: Configuration
Enable the theme in your `config.toml` in the site directory:
```toml
theme = "adidoks"
```
Or copy the `config.toml.example` from the theme directory to your project's
root directory:
```bash
cp themes/adidoks/config.toml.example config.toml
```
### Step 4: Add new content
You can copy the content from the theme directory to your project:
```bash
cp -r themes/adidoks/content .
```
You can modify or add new posts in the `content/blog`, `content/docs` or other
content directories as needed.
### Step 5: Run the project
Just run `zola serve` in the root path of the project:
```bash
zola serve
```
AdiDoks will start the Zola development web server accessible by default at
`http://127.0.0.1:1111`. Saved changes will live reload in the browser.
## Customisation
You can customize your configurations, templates and content for yourself. Look
at the `config.toml`, `theme.toml`, `content` files and templates files in this
repo for an idea.
### Global Configuration
There are some configuration options that you can customize in `config.toml`.
#### Configuration options before `extra` options
Set the authors's taxonomies for the site.
```toml
taxonomies = [
{name = "authors"},
]
```
Use search function for the content.
```toml
build_search_index = true
```
#### Configuration options under the `extra`
The following options should be under the `[extra]` in `config.toml`
- `language_code` - set HTML file language (default to `en-US`)
- `theme_color` - your site's HTML color (default to `#fff`)
- `title_separator` - the separator to your site title, like `|` and `-` (defaults to `|`)
- `title_addition` - the additon content for the title of the homepage
- `timeformat` - the timeformat for the blog article published date
- `timezone` - the timezone for the blog article published date
- `edit_page` (and `docs_repo`, `repo_branch`) - whether to show the edit page in the github repo for your docs
- `math` (and `library`) - set KaTeX or MathJax library
- `[extra.open]` - Open Graph + Twitter Cards for the site
- `[extra.schema]` - set JSON-LD for the site
- `[[extra.menu.main]]` - the header navigations for the site
- `[[extra.menu.social]]` - the social links on the header of the page
- `[extra.footer]` - the footer content on the left
- `[[extra.footer.nav]]` - the footer navigations on the right
### Templates
All pages are extend to the `base.html`, and you can customize them as need.
### Content
#### Homepage
Go to the *content/_index.md* file to add your own homepage content.
- `[extra]` - the main content of the homepage
- `[[extra.ist]]` - the lists' content of the homepage
#### Sections
Each section includes a `_index.md`, and you can customize it or add your new
section under the `content` folder.
#### Pages
There are mainly three types of pages in the site.
- `blog` - blog article
- `docs` - documentation article
- `authors` - authors page if you need to add some information for a new author
## Reporting Issues
We use GitHub Issues as the official bug tracker for the **AdiDoks**. Please
search [existing issues](https://github.com/aaranxu/adidoks/issues). It’s
possible someone has already reported the same problem.
If your problem or idea is not addressed yet, [open a new issue](https://github.com/aaranxu/adidoks/issues/new).
## Contributing
We'd love your help! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) to learn
about the kinds of contributions we're looking for.
## License
**AdiDoks** is distributed under the terms of the
[MIT license](https://github.com/aaranxu/adidoks/blob/main/LICENSE).