Skip to content

Latest commit

 

History

History
145 lines (102 loc) · 4.64 KB

README.md

File metadata and controls

145 lines (102 loc) · 4.64 KB

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