Documentation Site for BPRS Projects

This website holds the complete software and design process documentation for prjects done by mora-bprs team.

Instructions for team contributers

Get Started Now

1. Install Hugo to your respective platform - official Hugo website.

2. Git Clone with submodules and navigate

   git clone --recurse-submodules https://github.com/mora-bprs/mora-bprs.github.io.git && cd mora-bprs.github.io
   # or
   gh repo clone mora-bprs/mora-bprs.github.io -- --recurse-submodules && cd mora-bprs.github.io

3. Create a git branch if you haven't already

   git checkout -b <newbranchname>
   # example: git checkout -b thuva
   
   # if you already have a recommended branch to work on just checkout
   git checkout <branchname>

4. Make changes and Push

   • edit files inside docs/ directory referring hugo theme documentation
   • verify your changes in the site using the following command, locally hosted in localhost:1313

   hugo server -D

   • upload your changes to repo when you are confident and make a pull request

   git add .
   git commit -m "Description of changes made"
   git push origin <remotebranchname>

   • some tips: if you are still editing the file and don't want it to show up on the site set draft = true in the header of the md file.

Detailed Guide

• This guide assumes that you have previous experience with handling banches and private repos, if you want a more beginner friendly approach use the github commandline utility gh which will setup all the authetications and remote url handling for you.
• We are using the hextra template for our documentation site. And choosing the git submodule route to install the theme.
• Follow the steps to get the site working first and then add the content.

1. Install Hugo

   • Hugo is a fast Static Site generator written in golang, hence you have to install it to compile your templates to web format.
   • You can follow the installation instructions provided on the official Hugo website.

2. Clone the Repository with submodules and Navigate to the Directory

   git clone --recurse-submodules https://github.com/mora-bprs/mora-bprs.github.io.git && cd mora-bprs.github.io

3. Start Editing the Site:

   • Refer to this hugo theme documentation to edit the pages.
   • You can start editing the Hugo site by modifying the content files located in the content directory. They can use Markdown syntax to write content and make changes as needed.
   • First create a folder with the slug name in the content folder, then create an index.md file in that folder and write the content in it.
   • hugo server -D will give a preview of your site in localhost:1313

template for index.md file:

---
title: "Title of the page"
date: 2024-03-03
authors:
  - name: imfing
    link: https://go.io

tags:
  - Markdown
  - Example
  - Guide

draft: false
---

## Sample Markdown content

Here write the content of the page in markdown syntax.

Useful Commands

1. Preview Changes Locally:

   • To preview their changes locally, you can run the Hugo development server:

   hugo server -D
   #or
   hugo server --buildDrafts --disableFastRender

   This command starts a local web server, and you can view the site in their web browser at http://localhost:1313.

2. Generate the changes locally:

   • To generate the changes locally, you can run the Hugo command:

   hugo --destination docs

   This command generates the static files in the docs directory.

3. Commit Changes to the respective Branch:

   • Create a new branch when you run this for the first time.

     git checkout -b <newbranchname>
     # example: git checkout -b thuva

   • If this is not your first time working with dev branch do the following.

   • After making changes, you should commit their changes to the "dev" branch:

   • When multiple people are working it is recommended to create a branch using your name or something unique to your team and commit to that branch to avoid merge conflicts and remote HEAD conflicts.

     • Sasika: dev branch
     • Thuva: thuva branch

     git checkout <branchname>
     git add .
     git commit -m "Description of changes made"
     git push origin <remotebranchname>

4. Updating Submodules

git submodule update --remote

Acknowledgments

• Using Hugo Theme [https://github.com/imfing/hextra]