Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/opensourceway/asciidoc-blog

Support files for article on creating a blog using Asciidoc and Hugo
https://github.com/opensourceway/asciidoc-blog

Last synced: 7 days ago
JSON representation

Support files for article on creating a blog using Asciidoc and Hugo

Awesome Lists containing this project

README 

        

:Author:    Andy Thornton

:Email:     [email protected]



== Creating a blog using Asciidoc and Hugo

This repo contains source materials to accompany the article on opensource.com for getting started with Hugo and asciidoc as a web development platform.



[#img-homepage]

.The server

[link=https://raw.githubusercontent.com/opensourceway/asciidoc-blog/master/static/images/screenshot-homepage.png]

image::https://raw.githubusercontent.com/opensourceway/asciidoc-blog/master/static/images/screenshot-homepage.png[Demo Website]



==== Installing Asciidoc and Asciidoctor.

.Ubuntu

Asciidoc is available in the default repos.

[source,bash]

----

sudo apt-get install asciidoc asciidoctor -y

----



.Fedora

Asciidoctor can be installed using the gem command. Asciidoc is installed through the standard repos.

[source,bash]

----

yum install asciidoc

gem install asciidoctor

----



For more detailed installation information, visit the following guides.



.Installation Guides

* http://asciidoc.org/INSTALL.html[Asciidoc].

* http://asciidoctor.org/docs/install-toolchain/[Asciidoctor].



==== Installing Hugo

The best guide for https://gohugo.io/getting-started/installing/[installing Hugo] is on their website. I found it was worth following this guide rather than use the package maintained in the Ubuntu repo as it was older and caused problems with modern themes.



==== How do I use these files?

The repo contains a demo website with some sample articles in Asciidoc. The following folders are useful starting points.



.Clone the repo

[source,bash]

----

git clone [email protected]:opensourceway/asciidoc-blog.git

----

[#img-folders]

.Folder Structure

[link=https://raw.githubusercontent.com/opensourceway/asciidoc-blog/master/static/images/screenshot-folders.png]

image::https://raw.githubusercontent.com/opensourceway/asciidoc-blog/master/static/images/screenshot-folders.png[Folders Overview]



For more information, checkout the documentation on the https://gohugo.io/getting-started/directory-structure/[Hugo Homepage]



.Starting the server

From the root directory of the cloned repo:

[source,bash]

----

hugo server  --buildDrafts

----



This will run the server where you can see your website locally on http://localhost:1313[http://localhost:1313].



[#img-server]

.The server

[link=https://raw.githubusercontent.com/opensourceway/asciidoc-blog/master/static/images/screenshot-server.png]

image::https://raw.githubusercontent.com/opensourceway/asciidoc-blog/master/static/images/screenshot-server.png[Server Window]



To make changes to the setup, you can edit the config.toml file and set your website preferences up. The site contains initial setup parameters.



Content is available under the folder content/post. There are some example articles available to get you started.



== Working with Asciidoc

My personal preference is to use http://www.vim.org/download.php[Vim] for working with http://asciidoc.org/[Asciidoc],

there are a number of plugins which make working with Asciidoc easier as well as a http://www.vim.org/scripts/script.php?script_id=1832[syntax file] for highlighting your document.



If you are looking for something more visual, I would recommend the https://atom.io/[Atom editor] from GitHub.

It has plugins which provide a real-time preview of your work and makes it easier to work with GitHub.

Using Hugo, Asciidoc and the Atom editor, you have a complete publishing system with real time previews and a local server to run validation against.



[#img-atom]

.Atom Editor, click for full screen

[link=https://raw.githubusercontent.com/opensourceway/asciidoc-blog/master/static/images/screenshot-atom-editor.png]

image::https://raw.githubusercontent.com/opensourceway/asciidoc-blog/master/static/images/screenshot-atom-editor-thumbnail.png[Atom Editor with preview plugin]



== Where to go from here?

You can tailor the site in the config.toml file to personalise your setup. There are a number of https://themes.gohugo.io/[themes] available to further customise your site.

The language behind the more dynamic elements is very well implemented and there's excellent documentation on the Hugo website on how to get started working with https://gohugo.io/templates/[content and theming]. The theme used in this demo is the https://themes.gohugo.io/strata/[Strata Theme] by https://github.com/digitalcraftsman[Digitalcraftsman] which has detailed documentation on configuration options available on it's https://github.com/digitalcraftsman/hugo-strata-theme[github page].



== Thanks and credit due.



Thanks to http://spf13.com[Steve Francia] for https://gohugo.io/[Hugo], for producing a fun platform to play with.

The https://github.com/digitalcraftsman/hugo-strata-theme[Strata theme] port and the https://discourse.gohugo.io/[Hugo community].



Useful resources

++++++++++++++++



.Hugo

* https://gohugo.io/[Hugo]

 - https://gohugo.io/getting-started/installing/[Installation]

 - https://gohugo.io/getting-started/quick-start/[Quick Start Guide]

 - https://github.com/gohugoio/hugo[Github Repo]

 - https://gohugo.io/tools/starter-kits/[Starter Kits]

* https://themes.gohugo.io/[Hugo Themes]

* https://discourse.gohugo.io/[Community]



.Asciidoc

* http://asciidoc.org/[Asciidoc]

 - http://asciidoc.org/#_overview_and_examples[Code Examples]

 - http://asciidoc.org/userguide.html[User Guide]

 - http://powerman.name/doc/asciidoc[Cheat Sheet]

* http://asciidoctor.org/[Asciidoctor]



.Editors and Frontends

* https://atom.io/[Atom Editor]

* Vim Plugins

 - http://www.vim.org/scripts/script.php?script_id=1832[Asciidoc Syntax]

 - http://www.vim.org/scripts/script.php?script_id=2882[Markdown Syntax]



Demo and source materials

+++++++++++++++++++++++++

 * https://themes.gohugo.io/strata/[Strata Theme]

 * http://spf13.com/[Steve Francia's homepage] maintainer of Hugo