# 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.13.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).