readme and minor fixes
This commit is contained in:
codeandmedia
parent
a2667356f1
commit
cd1c3c0e5f
8 changed files with 84 additions and 56 deletions
19
README.md
Normal file
19
README.md
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
## An easy way to create a document library for your project
|
||||
|
||||
Demo: [https://easydocs.codeandmedia.com/](https://easydocs.codeandmedia.com/)
|
||||
|
||||
This theme for [Zola](https://getzola.org) (static site engine) helps you build and publish your project docs easily and fast. Zola is just one binary that outputs html-pages and additional static assets after building your docs written in Markdown. Thus, you can take the theme, your md-files, Zola and gain flexible and simple website for documentation.
|
||||
|
||||
### Step-by-step
|
||||
|
||||
As you may have heard Zola is quite flexible :) So, the scenario below is one of hundreds possible ways to make things done, feel free to find your best. Also, Zola provides their own mechanism to install and use themes, see [the docs](https://www.getzola.org/documentation/themes/installing-and-using-themes/).
|
||||
|
||||
1. Fork the repo and replace demo-content inside content folder with yours. But take a look to _index.md files. It contains `title` and when you want to have anchor right of your headers add `insert_anchor_links = "right"` to each index. `theme.toml`, screenshot and readme may be deleted too.
|
||||
2. Inside `config.toml` change URL and title on your own. In extra section you can specify path to your GitHub API for version below the logo on nav, favicon and logo itself. Or just remove the lines if you don't need it. Also, you can configure or turn on some additional settings related to Zola. [Specification is here](https://www.getzola.org/documentation/getting-started/configuration/).
|
||||
3. In sass/_variables.scss you may change font, color or backgound if you want.
|
||||
4. Almost done. Now, you should decide how you want to build and where will be hosted your website. You can build it locally and upload to somewhere. Or build in GitHub Actions and host on GitHub Pages / Netlify / CloudFlare Pages / AnyS3CloudStorage. [Howto for GitHub Pages](https://www.getzola.org/documentation/deployment/github-pages/). [My example](https://github.com/o365hq/o365hq.com/blob/main/.github/workflows/main.yml) of GitHub workflow with 2-steps build (the first checks for links and spelling errors, the second uploads to Azure). [Dockerfile](https://github.com/codeandmedia/zola_docsascode_theme/blob/master/Dockerfile) to make Docker image.
|
||||
|
||||
Enjoy your docs!
|
||||
|
||||
* _Icons: [Office UI Fabric Icons](https://uifabricicons.azurewebsites.net/)_
|
||||
* _Copy-code-button: [Aaron Luna](https://aaronluna.dev/blog/add-copy-button-to-code-blocks-hugo-chroma/)_
|
||||
|
|
@ -9,4 +9,5 @@ highlight_theme = "base16-ocean-light"
|
|||
|
||||
[extra]
|
||||
logo = "https://logoipsum.com/logo/logo-11.svg"
|
||||
release = "https://api.github.com/repos/getzola/zola/releases/latest"
|
||||
release = "https://api.github.com/repos/getzola/zola/releases/latest"
|
||||
favicon = "https://www.getzola.org/favicon.ico"
|
||||
|
|
@ -1,30 +1,24 @@
|
|||
+++
|
||||
title = "spec"
|
||||
title = "index"
|
||||
insert_anchor_links = "right"
|
||||
+++
|
||||
|
||||
## An easy way to create a document library for your project
|
||||
|
||||
Getting started
|
||||
- Installation
|
||||
- CLI usage
|
||||
- Directory structure
|
||||
- config.toml
|
||||
|
||||
Content
|
||||
- Organisation
|
||||
- Sections
|
||||
- Pages
|
||||
- Shortcodes
|
||||
- Internal links & deep linking
|
||||
- Table of contents
|
||||
- Syntax highlighting
|
||||
- Sass
|
||||
|
||||
Templates
|
||||
- Intro
|
||||
- Each kind of page and the variables available
|
||||
- Built-in global functions
|
||||
- Built-in filters
|
||||
Demo: [https://easydocs.codeandmedia.com/](https://easydocs.codeandmedia.com/)
|
||||
|
||||
Theme
|
||||
- Installing & customising a theme
|
||||
- Creating a theme
|
||||
This theme for [Zola](https://getzola.org) (static site engine) helps you build and publish your project docs easily and fast. Zola is just one binary that outputs html-pages and additional static assets after building your docs written in Markdown. Thus, you can take the theme, your md-files, Zola and gain flexible and simple website for documentation.
|
||||
|
||||
### Step-by-step
|
||||
|
||||
As you may have heard Zola is quite flexible :) So, the scenario below is one of hundreds possible ways to make things done, feel free to find your best. Also, Zola provides their own mechanism to install and use themes, see [the docs](https://www.getzola.org/documentation/themes/installing-and-using-themes/).
|
||||
|
||||
1. Fork the repo and replace demo-content inside content folder with yours. But take a look to _index.md files. It contains `title` and when you want to have anchor right of your headers add `insert_anchor_links = "right"` to each index. `theme.toml`, screenshot and readme may be deleted too.
|
||||
2. Inside `config.toml` change URL and title on your own. In extra section you can specify path to your GitHub API for version below the logo on nav, favicon and logo itself. Or just remove the lines if you don't need it. Also, you can configure or turn on some additional settings related to Zola. [Specification is here](https://www.getzola.org/documentation/getting-started/configuration/).
|
||||
3. In sass/_variables.scss you may change font, color or backgound if you want.
|
||||
4. Almost done. Now, you should decide how you want to build and where will be hosted your website. You can build it locally and upload to somewhere. Or build in GitHub Actions and host on GitHub Pages / Netlify / CloudFlare Pages / AnyS3CloudStorage. [Howto for GitHub Pages](https://www.getzola.org/documentation/deployment/github-pages/). [My example](https://github.com/o365hq/o365hq.com/blob/main/.github/workflows/main.yml) of GitHub workflow with 2-steps build (the first checks for links and spelling errors, the second uploads to Azure). [Dockerfile](https://github.com/codeandmedia/zola_docsascode_theme/blob/master/Dockerfile) to make Docker image.
|
||||
|
||||
Enjoy your docs!
|
||||
|
||||
* _Icons: [Office UI Fabric Icons](https://uifabricicons.azurewebsites.net/)_
|
||||
* _Copy-code-button: [Aaron Luna](https://aaronluna.dev/blog/add-copy-button-to-code-blocks-hugo-chroma/)_
|
||||
|
|
@ -89,7 +89,6 @@ pre {
|
|||
|
||||
code {
|
||||
font: $code_font;
|
||||
background: #eff1f5;
|
||||
}
|
||||
|
||||
.copy-code-button {
|
||||
|
|
@ -333,6 +332,10 @@ article {
|
|||
z-index:10;
|
||||
box-shadow: 0 2px 0 rgba(0,0,0,.1);
|
||||
}
|
||||
|
||||
#on_right {
|
||||
margin-top:$baseline;
|
||||
}
|
||||
}
|
||||
|
||||
@import "fabric-icons-inline";
|
||||
|
|
|
|||
BIN
screenshot.png
Normal file
BIN
screenshot.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 147 KiB |
|
|
@ -3,9 +3,15 @@
|
|||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<link rel="stylesheet" href="{{ get_url(path="main.css") | safe }}">
|
||||
{% if config.extra.favicon %}
|
||||
<link rel="icon" href="{{ config.extra.favicon | safe }}">
|
||||
{% endif %}
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1">
|
||||
<title>{% block title %}{{ config.title }}{% endblock title %}</title>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
{% if config.extra.release %}
|
||||
<script>
|
||||
fetch('{{ config.extra.release | safe }}')
|
||||
.then((response) => {
|
||||
|
|
@ -17,7 +23,7 @@
|
|||
release.innerHTML = `<a href='${html_url}'>${release_name}</a>`;
|
||||
});
|
||||
</script>
|
||||
|
||||
{% endif %}
|
||||
<main>
|
||||
|
||||
{% block nav %}
|
||||
|
|
@ -53,8 +59,8 @@
|
|||
|
||||
<ul class="subtree">
|
||||
{% for page in subsection.pages %}
|
||||
<li class="{% if current_path == page.path %}active{% endif %}">
|
||||
<a href="{{page.permalink}}">{{page.title}}</a>
|
||||
<li {% if current_path == page.path %}class="active"{% endif %}>
|
||||
<a href="{{page.permalink | safe }}">{{page.title}}</a>
|
||||
</li>
|
||||
|
||||
{% if current_path == page.path %}
|
||||
|
|
@ -80,20 +86,19 @@
|
|||
<li><a href="{{ h3.permalink | safe }}">{{ h3.title }}</a></li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
{% endif %}
|
||||
{% endif %}
|
||||
</li>
|
||||
{% endfor %}
|
||||
{% endfor %}
|
||||
</ul>
|
||||
{% endif %}
|
||||
{% endif %}
|
||||
|
||||
|
||||
{% endif %}
|
||||
|
||||
|
||||
{% endfor %}
|
||||
</ul>
|
||||
{% endfor %}
|
||||
</div> </nav>
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
</ul>
|
||||
{% endfor %}
|
||||
</div>
|
||||
</nav>
|
||||
{% endblock nav %}
|
||||
|
||||
<article>
|
||||
|
|
@ -111,25 +116,20 @@
|
|||
</div>
|
||||
{% endif %}
|
||||
|
||||
<div id="wrap">
|
||||
{% block content %}
|
||||
|
||||
|
||||
{{ section.content | safe }}
|
||||
|
||||
{% endblock content %}
|
||||
</div>
|
||||
<div id="wrap">
|
||||
{% block content %}
|
||||
{{ section.content | safe }}
|
||||
{% endblock content %}
|
||||
</div>
|
||||
|
||||
</article>
|
||||
</main>
|
||||
|
||||
|
||||
</main>
|
||||
|
||||
{% if config.build_search_index %}
|
||||
<script type="text/javascript" src="{{ get_url(path="elasticlunr.min.js") | safe }}"></script>
|
||||
<script type="text/javascript" src="{{ get_url(path="search_index.en.js") | safe }}"></script>
|
||||
<script type="text/javascript" src="{{ get_url(path="js.js") | safe }}" defer></script>
|
||||
{% endif %}
|
||||
{% if config.build_search_index %}
|
||||
<script type="text/javascript" src="{{ get_url(path="elasticlunr.min.js") | safe }}" defer></script>
|
||||
<script type="text/javascript" src="{{ get_url(path="search_index.en.js") | safe }}" defer></script>
|
||||
<script type="text/javascript" src="{{ get_url(path="js.js") | safe }}" defer></script>
|
||||
{% endif %}
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -1,4 +1,5 @@
|
|||
{% extends "index.html" %}
|
||||
{% block title %} {{ config.title }} | {{ page.title }} {% endblock title %}
|
||||
{% block content %}
|
||||
{{ page.content | safe }}
|
||||
{% endblock content %}
|
||||
10
theme.toml
Normal file
10
theme.toml
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
name = "EasyDocs"
|
||||
description = "An easy way to create docs for your project"
|
||||
license = "MIT"
|
||||
homepage = "https://github.com/codeandmedia/zola_easydocs_theme"
|
||||
min_version = "0.13.0"
|
||||
demo = "https://easydocs.codeandmedia.com"
|
||||
|
||||
[author]
|
||||
name = "Roman Soldatenkov"
|
||||
homepage = "https://codeandmedia.com"
|
||||
Loading…
Reference in a new issue