How to create docs

These docs are open source, which means that you can create your own pages and pull them into the repository. But with very little knowledge about structure of this site it can be hard to know what goes where. The goal of this tutorial is to help you learn how to create new pages.

At least basic knowledge of HTML is required to follow this tutorial.

Structure of the page

This page consists of a few important folders that you should know. The most important tutorials and docs folders. You should store the pages in them.

The images folder has images that are used in the pages, remember to store all of the used images in there.

And the css and js folders. The css folder is probably the least useful thing, because you don't need to know CSS syntax to program these pages. But js folder is more important than you probably would think. We will come back to it later.

Elements

For every page that we write we use already developed syntax. This page uses combination of classes assigned to div and a tags and HTML tags such as h3. Here's what everything does:

  • div
    • class="info" - An Information tag, communicates important information that may otherwise be overlooked.
    • class="warn" - A warning tag, indicates that caution should be used.
    • class="danger" - A danger tag, warns that an action may cause serious problems.
  • a
    • class="button" creates a clickable button.
    • without class creates a clickable link.
  • h3 is a title.
  • h2 is a subtitle.
  • p is a paragraph.
  • code is an inline code without syntax highlighting.
  • pre is a multi-line code snipper with line numbering.
    • class="syntax-java" Adds syntax highlighting for Java snippets

Writing a page

So finally after all of that we can move into writing your own page.

After explaining the syntax, there isn't actually that much to this, but you have to remember one very important thing. Always put your page's content inside the DIV with a card class.

So your page should like this:


Setting the header

On top of the documentation DIV there is a script tag containing a call to a function that will set the header text. The first parameter should be the article title, and the second parameter is an optional description, leave it blank if the title is self explanatory.

// Change these to the title of the documentation topic/item
setHeader("How to use the ECS", "Entity Component System.");
                

Adding it to the legend

After creating your page there is just one more thing to do. As you probably realized all of the pages are listed in the side navigation on the left, called the legend.

First open the js/insert/legendDocs.js or js/insert/legendTuts.js file (depends on what kind of page are you writing). There is a legend variable containing the HTML code for the legend.

If necessary, you can create new categories by using h3 tag, or just add your pages to existing categories.
Make a new list element with a li tag, inside of it put a tag leading to the page you just created.

In the legend, it is critical to use root paths to your page, not relative paths. Also, do not forgot about the ${lp} element, it appends the correct base URL depending where the page is being accessed from.
A good link will look similar to this: <li><a href="${lp}/docs/blob.html">Foo</a></li>

After all of that your legend variable should look like this:

let legend = `

Category

// Rest of the legend code `;

Summary

You've done it. You created your own documentation or tutorials page. Now you can pull it to the main branch of the repository.

From all of the Azurite-Docs contributors we all thank you for your willingness to contribute to the Azurite Docs and for being part of the Azurite Engine community.