githubdocs - GitLite

KO | EN

gitlite — search

#javascript #python #react #ai #typescript #android #java #windows #vue #awesome-list #pytorch #mcp #openai #open-source

githubdocs

(★ 142)

Easily build a searchable documentation app using markdown files in your Github Repo or local Markdown files.

File Explorer

Download Latest Version (.zip)

- config.json
- exampleDocs.json
- 1 - Introduction.md
- 2 - Installation.md
- 3 - How it works.md
- 4 - Github repository.md
- 5 - Local files.md
- 6 - Configuration.md
- 7 - Theming.md
- common.js
- - mobile.png
  - responsive.png
- - main.js
  - main.min.js
- - material-style.css
  - material-style.min.css
  - style.css
  - style.min.css
- favicon.ico
- index.js
- - layout.hbs
  - material.hbs
- default.hbs
- material.hbs
.eslintignore
.eslintrc.json
.gitignore
app.js
package-lock.json
package.json
README.md

# Installation Guide

1. Get the code

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

Downloads the entire project code from GitHub to your computer.

cd githubdocs

Moves into the project folder you just downloaded.

2. Node.js

Easy Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Node.js Node.js must be installed to use npm. The LTS version is recommended.

npm install

Downloads and installs the libraries listed in package.json.

npm start

Starts the development/run server.

✅ After running the command, open the address shown in the terminal (usually something like http://localhost:3000) in your browser.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Githubdocs

Easily build a searchable documentation Single Page Application (SPA) using markdown files in your Github Repo or local Markdown files. Github docs is a lightweight alternative to Gitbooks allowing simple but powerful Markdown generate documentation websites.

## Website from Github Repo

### Installation

1. Clone Repository: `git clone https://github.com/mrvautin/githubdocs.git && cd githubdocs`
2. Install dependencies: `npm install`
3. Start application: `npm start`
4. Go to  [http://127.0.0.1:5555](http://127.0.0.1:5555) in your browser

### Demo

[https://githubdocs.markmoffat.com](https://githubdocs.markmoffat.com)

### Markdown files

The docs menu and files are built using files from your Github repo set in the config. Files should have the title of the doc in a single markdown hash/# (HTML = H1) tag in the file. This is used to build the slug of the doc and the menu title etc.

See example docs here: [https://github.com/mrvautin/githubdocs/tree/master/docs](https://github.com/mrvautin/githubdocs/tree/master/docs)

### Search

Search is built using [js-search](https://github.com/bvaughn/js-search). The index is built and stored in memory on startup. When searched from the client the API is called returning any matching docs. The menu will then display the match docs. When the search term is removed, the full list of docs is returned.

### Config

The config file is located here: `/config/config.json`.

An example config:

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

|Setting|Description|
|--- |--- |
|`title`|Sets the value to be displayed at the top of the page|
|`githubRepoOwner`|Owner/username of the Github repo|
|`githubRepoName`|Name of the repo holding the Markdown files|
|`githubRepoPath`|Directory relative to the root of the repo holding the Markdown files|
|`updateDocsCron`|A cron schedule to reindex your Markdown files/docs from Github or static|
|`addAnchors`|Transforms H1, H2, H3, H4, H5 info HTML anchor points for easy sharing|
|`menuItems`|Not sure how useful this is. Set the menu items in the top navigation|
|`static`|Reads Markdown files statically from `/docs` folder. Defaults to `false`|

## Static websites

It's also possible to create a site from local Markdown files rather than using a Github repo.

### Starting

You can start your website using the following command from the root of your app:

```
node app.js
```

### Static

To do this you place your Markdown files into the `docs` folder and set `static` to `true` in your config.

An example `config.json` for a static site:

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

### Layouts

You can also specify your own layout file. The default `views/layouts/layout.hbs` file is used unless you specify a different file in your `config.json`.

``` json
{
    "layoutFile": "material.hbs"
}
```

Included is a `material.hbs` design template and a Bootstrap template (`default.hbs`).