Welcome to the future of documentation! Today, we’ll unpack how to effortlessly create a Single Page Application (SPA) for your documentation using Markdown files from your GitHub repository or from your local files. With GitHub Docs, you can enjoy a lightweight alternative to Gitbooks, providing a robust solution for generating documentation websites.

Installation Steps

Let’s roll up our sleeves and get started with setting things up.

1. Clone the Repository:

git clone https://github.com/mrvautin/githubdocs.git

2. Navigate to the Project Directory:

cd githubdocs

3. Install Dependencies:

npm install

4. Start the Application:

npm start

5. Open your Browser:

Navigate to http://127.0.0.1:5555.

Demo

Check out a live demonstration at this link.

Working with Markdown Files

The magic of GitHub Docs largely revolves around Markdown files. Your documentation menu and files are generated from these Markdown files, which should include a title using a single hash tag (#) at the beginning. This title is essential as it helps to build both the slug for the documentation and its representation in the menu.

You can check example docs here: Example Docs.

Search Functionality

Searching through your documentation is enabled using js-search. Upon startup, the index of documents is built and stored in memory. When a user searches for a term, the API retrieves matching docs, which populate the menu. Clearing the search term will show all documents again.

Configuration Settings

Your configuration is managed via a JSON file, specifically located at config/config.json. Here is an example of the configuration structure:

{
    "title": "githubdocs",
    "githubRepoOwner": "mrvautin",
    "githubRepoName": "githubdocs",
    "githubRepoPath": "exampleDocs",
    "updateDocsCron": "*5 * * * *",
    "addAnchors": true,
    "menuItems": [
        {
            "menuTitle": "About",
            "menuLink": "about"
        },
        {
            "menuTitle": "Contact",
            "menuLink": "contact"
        }
    ],
    "static": false
}

Understanding the Configuration Settings

Let’s break down the configuration settings with an analogy:

Imagine you are crafting a recipe. Each ingredient, the temperature for baking, and cook time correlates with the configuration settings. The title is like the name of the recipe — it tells everyone what dish they are about to make. The owner’s username and repository name are akin to the author of the recipe and where it’s published—verifying confidence in its authenticity. The cron schedule for updating docs resembles setting a reminder on your calendar to check on the dish periodically, ensuring it is cooked to perfection. Finally, the menu items provide your guests a guide to the delicious variety of recipes available, making the entire meal experience more enjoyable!

Creating Static Websites

Besides working with GitHub repositories, you can also build a website using local Markdown files. Follow these steps:

1. Run your application using the command:

node app.js

2. Place your Markdown files into the docs folder.
3. Set static to true in your config.

Here’s an example configuration for a static site:

{
    "title": "githubdocs",
    "githubRepoOwner": "mrvautin",
    "githubRepoName": "githubdocs",
    "githubRepoPath": "exampleDocs",
    "updateDocsCron": "*5 * * * *",
    "addAnchors": true,
    "menuItems": [
        {
            "menuTitle": "About",
            "menuLink": "about"
        },
        {
            "menuTitle": "Contact",
            "menuLink": "contact"
        }
    ],
    "static": true
}

Custom Layouts

You also have the option to specify a custom layout file. By default, the application uses the file views/layouts/layout.hbs. If you want to use a different design for your documentation, this is where you make that change. For example:

{
    "layoutFile": "material.hbs"
}

You can opt for the included material.hbs design template or use the default Bootstrap template.

Troubleshooting

If you run into any issues during setup or usage, consider the following tips:

• Ensure Node.js and npm are installed correctly.
• Check if you are pointing to the correct repository in the configuration file.
• Make sure all dependencies are installed before starting the application.
• If the browser fails to load, verify that you are using the correct URL: http://127.0.0.1:5555.

For more insights, updates, or to collaborate on AI development projects, stay connected with fxis.ai.

At fxis.ai, we believe that such advancements are crucial for the future of AI, as they enable more comprehensive and effective solutions. Our team is continually exploring new methodologies to push the envelope in artificial intelligence, ensuring that our clients benefit from the latest technological innovations.