Skip to content
Permalink

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: aaranxu/adidoks
Failed to load repositories. Confirm that selected base ref is valid, then try again.
Loading
base: main
Choose a base ref
...
head repository: shellrs/adidoks
Failed to load repositories. Confirm that selected head ref is valid, then try again.
Loading
compare: main
Choose a head ref
Able to merge. These branches can be automatically merged.
  • 1 commit
  • 3 files changed
  • 1 contributor

Commits on Jan 7, 2024

  1. Updated Theme for Blog Posts (#1)

    * Modified the macro to display blog authors
    
    * Updated README
    AryanAb authored Jan 7, 2024
    Copy the full SHA
    2c186a0 View commit details
Showing with 40 additions and 165 deletions.
  1. +29 −164 README.md
  2. +6 −0 templates/blog/page.html
  3. +5 −1 templates/macros/page-publish-metadata.html
193 changes: 29 additions & 164 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,177 +1,42 @@
# Zola Theme AdiDoks
# AdiDoks Fork for shrs

AdiDoks is a modern documentation theme, which is a port of the Hugo
theme [Doks](https://github.com/h-enk/doks) for Zola.
This is a fork of the Zola [AdiDoks](https://github.com/aaranxu/adidoks) theme used for the shrs website. This README will cover the changes made for this fork specifically. You can check [Zola documentation](https://www.getzola.org/documentation/getting-started/overview/) separately.

## Demo
## Documentation

[Live Preview](https://adidoks.netlify.app/).
### Table of Contents

## Requirements
* [Authors List](#authors-list)
* [Image Styles](#image-styles)

Before using the theme, you need to install the [Zola](https://www.getzola.org/documentation/getting-started/installation/) ≥ 0.15.0.
### Authors List

## Quick Start
A list of authors can be given in the frontmatter metadata of each blog post. The names do not appear on the post summaries, but they do appear in the title section of each blog. The list consists of two parts: The name and an associated link. Note that the link is an optional parameter. If a link is provided, then the name appears as a hyperlink. An example is given below:

```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.
```yaml
title: "First Post"
url: "example.com/first-post"
# ... other frontmatter parameters ...
extra:
auhtors:
- name: John Doe
href: "https://johnswebsite.com"
- name: Jane Doe

### 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
The associated macros are in `page-publish-metadata.html` and can be used in template files.

We'd love your help! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) to learn
about the kinds of contributions we're looking for.
### Image Styles

## License
Images can be added to blog posts using the standard markdown syntax. For blog posts, the styling can be specified in `page.html`. Currently, the only styling applied will limit the width of the image to that of the blogs container.

**AdiDoks** is distributed under the terms of the
[MIT license](https://github.com/aaranxu/adidoks/blob/main/LICENSE).
```html
{% block body %}
{% set page_class = "blog single" %}
<style>
img {
max-width: 100%;
}
</style>
{% endblock body %}```
6 changes: 6 additions & 0 deletions templates/blog/page.html
Original file line number Diff line number Diff line change
@@ -10,6 +10,11 @@

{% block body %}
{% set page_class = "blog single" %}
<style>
img {
max-width: 100%;
}
</style>
{% endblock body %}

{% block header %}
@@ -25,6 +30,7 @@
<div class="blog-header">
<h1>{{ page.title }}</h1>
{{ macros_publish::page_publish_metadata(page=page) }}
{{ macros_publish::page_list_authors(page=page) }}
</div>
{% if page.extra.lead %}<p class="lead">{{ page.extra.lead | safe }}</p>{% endif %}
{{ page.content | safe }}
6 changes: 5 additions & 1 deletion templates/macros/page-publish-metadata.html
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
{% macro page_publish_metadata(page) %}
<p><small>Posted {{ page.date | date(format=config.extra.timeformat | default(value="%Y-%m-%d %H:%M:%S"), timezone=config.extra.timezone | default(value="America/New_York")) }}{% if page.taxonomies.authors and config.taxonomies %} by {% for author in page.taxonomies.authors %}{% if author_flag %} and {% endif %}<a class="stretched-link position-relative" href="{{ get_taxonomy_url(kind='authors', name=author) | safe }}">{{ author }}</a>{% set_global author_flag = true %}{% endfor %}{% endif %}&nbsp;&hyphen;&nbsp;<strong>{{ page.reading_time }}&nbsp;min read</strong></small><p>
<p><small>Posted {{ page.date | date(format=config.extra.timeformat | default(value="%Y-%m-%d %H:%M:%S"), timezone=config.extra.timezone | default(value="America/New_York")) }}</small><p>
{% endmacro %}

{% macro page_list_authors(page) %}
<p><small>{% if page.extra.authors %} by {% for author in page.extra.authors %}{% if author_flag %} and {% endif %} {% if author.href %} <a class="stretched-link position-relative" href="{{ author.href }}">{{ author.name }}</a>{% else %} {{ author.name }} {% endif %}{% set_global author_flag = true %}{% endfor %}{% endif %}</small></p>
{% endmacro %}