Shiavault Library

Shiavault.com utilizes this library to serve its pages and books. The books are found under the /books folder in Markdown format, which makes it easy to write and read without spending too much time on learning its syntax. The purpose of having open-source library of books is to make it easy to contribute fixes and new books while leveraging GitHub's (and Git's) collaborative capabilities. Unlike other sites which may simply lack any editing capability, Shiavault.com has been built with collaborative work in mind, with minimal central of control.

Overview

To understand this library, let's understand its hierarchy:

|- books
  |- a-bundle-of-flowers  
    |- 1-introduction.md  # First chapter
    |- 2-preface.md       # Second Chapter
    |- ...
    |- metadata.yml       # Information about the book itself

As can be intuitively seen, the chapters are basic Markdown files. You can directly edit them like any other Markdown file. The only technical file is the metadata.yml. Let's understand it further:

---
source: :alislam
source_url: http://www.al-islam.org/a-bundle-of-flowers-sayyid-faqih-imani
publisher: Amir al-Mu'mineen Ali (a.s.) Library
compiler: Ayatollah Sayyid Kamal Faqih Imani
translator: Sayyid Abbas Sadr-'ameli
title: A Bundle of Flowers
slug: a-bundle-of-flowers
uuid: f9ec9c60-78b4-4541-b902-c47e57c79ae8
description: |
  An excellent collection of traditions from the Ahlul Bayt, organized
  according to topics such as the knowledge of God, Invocation and social
  issues.
chapters:
- source: :alislam
  source_url: http://www.al-islam.org/a-bundle-of-flowers-sayyid-faqih-imani/introduction
  title: Introduction
  slug: 1-introduction
  uuid: aa164a6b-87d1-4f14-a54f-da1da1e990ac
- source: :alislam
  source_url: http://www.al-islam.org/a-bundle-of-flowers-sayyid-faqih-imani/preface
  title: Preface
  slug: 2-preface
  uuid: 8fabde36-a02b-40a5-b613-488af3b7bbaf

Here there is plenty of information about the book itself, such as who is the author, the title, a summary description, etc. You'll also find technical information about the book such as the source of the book (where it was found), the slug (which is what appears in the URL of the book), UUID (a unique identifier of this book), etc.

The metadata.yml thus only provides information about the book, and is not any part of the book itself. This file only needs to be edited whenever you'd want to update the book's summary description, chapter titles, or misc information such as author, compiler, publisher, etc.

Contributing

With an understanding of the organization, it should now be easy to understand how to contribute.

Getting Started

If you understand Git and GitHub, you are already good to get started. Simply fork this repository, and submit Pull Requests. However for those that do not, I recommend the following sources:

Editing an Existing Book

Open the appropriate chapter files and edit it
Submit a Pull Request

Adding a Book

Create a new folder under /book
Add chapters in order, e.g. 1-introduction.md
Add metadata.yml that provides information about the book
Submit a Pull Request