Creating a clean and efficient documentation site can be a breeze with the Jekyll Doc Theme. This guide will walk you through the steps to set it up locally, deploy using Docker, and integrate with GitHub Pages.

Running Jekyll Doc Theme Locally

Before diving into the setup, ensure you have Ruby and gem installed on your system. If you haven’t set these up yet, you can find installation instructions on the official Ruby website. Once you are ready, follow these steps:

• Install Bundler: This gem is vital for managing dependencies.
• Clone the Theme: Get the theme files to your workspace.
• Install Dependencies: This step ensures all necessary packages are ready for use.
• Run Jekyll: Serve your documentation locally to see it in action.

The detailed commands to achieve this are:

gem install bundler
git clone https://github.com/aksakalli/jekyll-doc-theme.git
cd jekyll-doc-theme
bundle install
bundle exec jekyll serve

Understanding Theme Assets

As the Jekyll Doc Theme has transitioned to support GitHub Pages, several files have been organized into an asset folder to improve accessibility:

• CSS
• Fonts
• Images (img)
• JavaScript (js)
• 404.html
• allposts.html
• search.json

Using Docker for Deployment

If you’re looking for a more robust solution, consider deploying your site with Docker. This method boasts better performance courtesy of Nginx. Here’s how you can set it up:

• Build the Docker Image: Use the provided Dockerfile to create your image with the desired base URL.
• Serve the Application: Run your configured image to make your documentation accessible.

Here are the commands you need:

docker build --build-arg JEKYLL_BASEURL=your-baseurl -t jekyll-doc-theme .
docker run -p 8080:80 jekyll-doc-theme

Integrating with GitHub Pages

To publish your documentation on GitHub Pages, you can utilize the Remote Theme plugin. Make sure to configure your Gemfile and _config.yml accordingly:

# In your Gemfile
# Remove the jekyll gem if using GitHub Pages
# Uncomment this:
gem 'github-pages', group: :jekyll_plugins

# In your _config.yml
remote_theme: aksakalli/jekyll-doc-theme@gh-pages

Customizing Theme Assets

Sometimes, simply using a theme isn’t enough; you may want to customize its appearance. Here’s a neat analogy: think of the theme as a delicious pie, and customizing is like adding your favorite toppings. To do this:

• Copy the necessary CSS files from the theme into your project.
• Modify the variables as desired.
• Make sure to import any additional styles post the standard imports.

Troubleshooting Tips

If you encounter any issues during the setup or deployment process, here are some helpful troubleshooting ideas:

• Dependency Issues: Ensure all gems are installed correctly by running `bundle install` again.
• Docker Errors: Make sure your Docker installation is running smoothly and check the base URL argument.
• File Not Found: Double-check file paths and names when copying assets.

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

Examples of Projects Using Jekyll Doc Theme

This theme has been implemented in various projects such as:

• teavm.org
• ogb.stanford.edu
• griddb.org
• contextmapper.org
• ai.cs.ucl.ac.uk
• …and many more!

Conclusion

By following the steps in this guide, you will have your very own documentation site up and running in no time! 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.