diff options
Diffstat (limited to 'exampleSite/content/getting-started')
-rw-r--r-- | exampleSite/content/getting-started/_index.md | 14 | ||||
-rw-r--r-- | exampleSite/content/getting-started/installation.md | 48 | ||||
-rw-r--r-- | exampleSite/content/getting-started/usage.md | 86 |
3 files changed, 148 insertions, 0 deletions
diff --git a/exampleSite/content/getting-started/_index.md b/exampleSite/content/getting-started/_index.md new file mode 100644 index 0000000..db293bd --- /dev/null +++ b/exampleSite/content/getting-started/_index.md @@ -0,0 +1,14 @@ ++++ +title = "Getting started" +description = "" +weight = 1 ++++ + +{{< lead >}} +Get started with Ace docs, the easy way to generate a static website for your project's documentation. +{{< /lead >}} + +Installation and configuration is easy and can be easily applied to any project. No need to be dependent on Python, Ruby or Java. Hugo runs from a simple binary and works through the command line. +Explore the following pages to learn how to build awesome documentation for your project using Ace. + +{{< childpages >}}
\ No newline at end of file diff --git a/exampleSite/content/getting-started/installation.md b/exampleSite/content/getting-started/installation.md new file mode 100644 index 0000000..87cc285 --- /dev/null +++ b/exampleSite/content/getting-started/installation.md @@ -0,0 +1,48 @@ ++++ +title = "Installation" +description = "" +weight = 1 ++++ + +{{< lead >}} +Installing Ace is easy. Just install the Hugo binary, create a new site and install the Ace theme. +{{< /lead >}} + +## Installing Hugo +In order to run this theme, you need to install Hugo on your system. +For more detailed information and other methods of installation you can visit the <a href="https://gohugo.io/getting-started/installing/" target="_blank">Hugo installation guide.</a> + +There may be other ways to install Hugo that are more applicable for your project. For example, you can use the NPM package <a href="https://www.npmjs.com/package/hugo-bin" target="_blank">hugo-bin</a> to include Hugo in a project that already uses NPM packages. + +### Checking your Hugo installation +Run the following command in your terminal to check if Hugo is installed. +{{< code lang="bash" >}} +hugo version +{{< /code >}} + +## Creating a site +Create a new site *docs* (you may choose any name you want). In your projects root folder, run the following command: +{{< code lang="bash" >}} +hugo new site docs +{{< /code >}} +This will create a new folder <code>/docs</code> with all required files in it. + +### Installing the theme +Download and copy the theme files into <code>/docs/themes/ace-documentation</code> or use <i>git</i> to clone the repository to that directory: +{{< code lang="bash" >}} +cd docs +cd themes +git clone https://github.com/vantagedesign/ace-documentation +{{< /code >}} + +After theme installation, the <code>/docs/themes/ace-documentation</code> folder should contain the file <code>theme.toml</code>, along with all other theme files. + +### Configuring your hugo site to use the theme +Inside your site's folder, <code>/docs</code>, you will find a file called <code>config.toml</code>. This is the configuration file for your site. Open it and configure it to use the Ace theme by setting the following value: +{{< code lang="toml" >}} +theme = "ace-documentation" +{{< /code >}} + + +## Installing example content +You can add some sample content to your site by placing the contents of the <code>exampleSite</code> directory in your <code>/docs</code> directory. diff --git a/exampleSite/content/getting-started/usage.md b/exampleSite/content/getting-started/usage.md new file mode 100644 index 0000000..53b2539 --- /dev/null +++ b/exampleSite/content/getting-started/usage.md @@ -0,0 +1,86 @@ ++++ +title = "Usage" +description = "" +weight = 2 ++++ + +{{< lead >}} +With the site created and the theme installed, it's time to run the server and create content. +{{< /lead >}} + +## Starting & building the site +### Development server +To start the site for development mode, execute the following command while in your <code>/docs</code> folder: +{{< code lang="bash" >}} +hugo server +{{< /code >}} +This will start a server on your localhost that will live-update with any changes you make to your site. + +For more Hugo commands visit <a href="https://gohugo.io/commands/" target="_blank">https://gohugo.io/commands/</a> + +### Building for production +To build the site for your production environment, as in, to serve it to your users through a web server, execute the following command. This will create a folder <code>/docs/public</code> with all the necessary files, compiled to HTML. + +<br>Be sure the site's configuration in <code>config.toml</code> is complete, including the <code>baseURL = "https://yourdomain.com/"</code> value to properly load stylesheets and other resources. +{{< code lang="bash" >}} +hugo +{{< /code >}} + + +## Creating content +### Markdown +Pages are written in Markdown and files defining pages should end with *.md*. For more information on how to use Markdown, search for tutorials on the internet or use this <a href="https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet" target="_blank">cheatsheet</a>. + +### File structure +Ace looks at your file stucture and automatically turns it into a menu. +The structure looks as follows: +{{< code >}} +/content +├── _index.md +├── page-top.md +└── /level-one + ├── _index.md + ├── page-1-one.md + ├── page-1-two.md + └── /level-two + ├── _index.md + ├── page-2-one.md + ├── page-2-two.md + └── /level-three + ├── _index.md + ├── page-3-one.md + ├── page-3-two.md + └── /level-four + ├── page-4-one.md + └── page-4-two.md +{{< /code >}} + +Your 'homepage' for every level is the <code>_index.md</code> file. Subpages (like <code>page-1-one.md</code>) are automatically added as child pages in the menu. + +An exception exists for the top level files. <code>/content/_index.md</code> is your homepage, and any other page files in the <code>/content</code> folder are not automatically added in the menu. Instead, they can be accessed manually through their URL (<code>yourdomain.com/page-title</code>). + +### File contents +Every file should start by defining the title and weight of the page. This can be done by adding the following text to the top of your page file. +{{< code lang="markdown" >}} ++++ +title = "Usage" +description = "" +weight = 2 ++++ +{{< /code >}} +The title will be displayed as a H1 header at the top of your page. The weight determines the order in the menu. + +After that you may write the content you desire with Markdown. You may use shortcodes to add some more 'advanced' layout features to the page, such as code hightlighting, a 'lead' style paragraph, images, video's, and more. + +### Navigation bar menu +While the left sidebar navigation is automatically populated by the file structure described above, and the right 'table of contents' sidebar menu is automatically populated by the headings defined on a page, the top navigation bar needs to be configured manually. +<br> +This can be done in the <code>config.toml</code> file, by adding the following lines: +{{< code lang="toml" >}} +[[menu.shortcuts]] +name = "<i class='fab fa-github'></i>" +url = "https://github.com/vantagedesign/ace-documentation" +weight = 10 +{{< /code >}} + +This example will create a GitHub icon that links to that URL. Instead of an icon, you may also use text, or both.
\ No newline at end of file |