# docindex

> Create Lightweight MD Document Listing Web Pages

Latest version **0.0.5** (published 2021-03-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install docindex
pnpm add docindex
yarn add docindex
bun add docindex
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 0.0.5 |
| Published | 2021-03-17 |
| First published | 2020-01-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 32.1 KB |
| Known vulnerabilities | 0 (+19 in 4 direct dependencies) |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Olli Hollmen |
| Maintainers | ohollmen |
| Keywords | doc, documentation, technical documentation, markdown, document website |

## Links

- npm: https://www.npmjs.com/package/docindex
- Repository: https://github.com/ohollmen/docindex
- Homepage: https://github.com/ohollmen/docindex#readme
- Issues: https://github.com/ohollmen/docindex/issues
- npm.io page: https://npm.io/package/docindex

## Dependencies (4)

- [jquery](https://npm.io/package/jquery.md) ~2.1.4
- [showdown](https://npm.io/package/showdown.md) ~1.2.2
- [bootstrap](https://npm.io/package/bootstrap.md) ~3.3.5
- [jquery-ui](https://npm.io/package/jquery-ui.md) ~1.12.1

## Alternatives

- [@cantoo/pdf-lib](https://npm.io/package/@cantoo/pdf-lib.md) — 297.9K weekly downloads
- [datatables.net-buttons](https://npm.io/package/datatables.net-buttons.md) — 200.1K weekly downloads
- [@ckeditor/ckeditor5-export-pdf](https://npm.io/package/@ckeditor/ckeditor5-export-pdf.md) — 167.0K weekly downloads
- [scanbot-web-sdk](https://npm.io/package/scanbot-web-sdk.md) — 15.0K weekly downloads
- [@syncfusion/ej2-angular-pdfviewer](https://npm.io/package/@syncfusion/ej2-angular-pdfviewer.md) — 8.8K weekly downloads

## Recent versions

- 0.0.5 (latest) — 2021-03-17
- 0.0.4 — 2020-08-20
- 0.0.3 — 2020-01-03
- 0.0.2 — 2020-01-03
- 0.0.1 — 2020-01-02

## README

## Docindex - Simple way of creating Markdown Doc collection pages

Provides a basic toolkit for building simple markdown document pages
with documents grouped by topic.

Docindex has very low dependencies:
- JQuery is currently used for loading docindex.json and MD docs.
- JQuery UI can provide Accordion option when "acc" option is set.

### DocIndex JSON Format

Expects server to contain a JSON file in simple format describing
docs and groups (JSON decorating with JS comments for doc and tutoring purposes, do not have these in your docindex.json):
```
{
  "groups": {
    "crafts": "Crafts and Arts",
    "sports": "World of Sport",
    "history": "Historical Events",
    // ...
  },
  "docs" : [
    {
     // Title as it appears on Docindex accordion.
     "title": "Ted Williams - Greatest Baseball Hero", 
     "urlpath": "ted_williams.md", // URL to doc (relative to curr page)
     "grp": "sports" // Optional Group that doc belongs to (See "groups" above)
    }
    // ...
  ]
}
```

Format has following members and sections (on top level):

- "title"  - Title (string) of Document page
- "docs"   - Array of Objects with each doc declared by title,urlpath,grp (See below)
- "groups" - Optional grouping of documents (in Object)
  - Missing "groups" will be auto-detected and sane behaviour will be
    triggered
  - Groups will appear as (JQuery UI) Accordion items on page

As further demonstrated by example docindex.json (above) the object nodes in "docs" have
following members:

- "title"   - Name of the Doc as it should appear in left side doclisting.
- "urlpath" - URL of document (relative to docroot or current URL of web server)
- "grp"     - Group that doc should fall under (when using groups)

## Setting up Docindex

### Installing from Github or NPM

For "NPM Install" make sure you have either `npm` or `yarn` package manager installed on your system.

From Github:

      git clone https://github.com/ohollmen/docindex.git

From NPM (If this made it's way to NPM):

      npm install docindex
      # ... OR ...
      yarn add docindex

### Wrapping HTML Page

HTML Page that docindex uses must have 2 divs with specific id:s declared:
- sidebar - Left side document listing and navigation area
- doccontent - Area to display document in

See section "Config Options ..." and "doclistid" and "docareaid" for configurability.

### Using Docindex in your JS

     window.onload = function () {
       // Create docIndex with settings overriden (as needed)
       var cfg = new docIndex({linkproc: "post"});
       // Load Doc index file and group listings data.
       $.getJSON("docindex.json", function (d) { cfg.initdocs(d); });
     };

### Config Options for docIndex

Allow passing in configuration with:

- "postloadcb" - Post DocIndex JSON load callback, gets passed docindex.json data structure (default: none). Allows manipulating (e.g. filtering) structure, no need to return value.
- "linkproc" - HTML Anchor / link processing policy (none,post,auto, default: none) - See below
- "pagetitleid" - Page title element inside HTML body (default: "pagetitle", which works for the bundled default page)
- "doclistid" - Doc Listing sidebar element ID to present as Accordion (default: "sidebar")
- "docareaid" -  Document HTML content display area (default: "doccontent")
- "acc" - Use JQuery UI (collapsible) Accordion (default: false)
- "avoidcaching" - Set additional unique parameters (without specific meaning) on URL:s
   to avoid caching (on client side)
- "debug" - Produce verbose messages to console (at various parts of execution)

Whenever defaults are good - you don't need to bothe passing anything.

### URL Link (URL-to-HTMLanchor) conversions

There are 3 options to process URL Links to HTML Anchor ("a") elements:

- none - No processing or conversions are done
- auto - If anchor ("a") elements are detected in document it is assumes that MD author
    had all URL:s she/he wants as links authored as anchors already in MD markup. If no
    links are found full URL-to-anchor conversion is 
- post - All remaining non-anchor URL:s in document are unconditionally converted.

## Web server

Run any web server capable of delivering static content.
You should be able to test your docindex.json by simply creating a symlink from your document directory to bundled docindex.html (e.g.):

     # For NPM Install
     ln -s node_modules/docindex/docindex.html docindex.html
     # For Github install (Assumes docindex got cloned to
     # subdir docindex of current directory)
     ln -s docindex/docindex.html docindex.html

Example for running python (lightweight) web server - good at least for testing:

     > python -m SimpleHTTPServer
     Serving HTTP on 0.0.0.0 port 8000 ...


Access the page via URL: http://localhost:8000/docindex.html (Use as basename whatever
name you created symlink by).

## Usage forms of docindex

- Use as-is: Simple use case may allow to using the docindex.html example (and associated CSS) and docIndex module as is. Only create a docindex.json for *your* docs (docindex toolkit will use this to create docindex page).
- Use almost as-is: Hack HTML and CSS to suite your need and style
- Use as a toolkit: Above plus use individual calls to JS api
- Use as an concept: You think that docindex is inflexible and sucks but
  you need a similar solution to manage Markdown docs. Write your own !

## Running the Included Demo

You either cloned docIndex from git or installed it by NPM (or yarn).

Flow for Git Install, run in the top level ("docindex") directory of the clone:
    
    # npm or yarn install for dependencies
    npm install
    # Cannot Install docindex itself by NPM rules (npm install docindex) !
    # So fake "docindex as dependency of itself" by a symlink:
    pushd node_modules; ln -s .. docindex ; popd
    # Usess included docindex file (docindex.demo.json)
    # Run web server (of your preference, here minimal python web server for static content)
    python -m SimpleHTTPServer
    # Look at URL http://localhost:8000 with browser

Flow for NPM based install (for another app, which has docindex in package.json or by running npm install docindex woithout any
package.json driving the installation):

    cd node_modules/docindex
    # Make appropriate symlinks
    ln -s .. node_modules
    # Or brute force install dependencies in sub-directories of "docindex"
    # npm install
    # Run web server ... (see above)
    python -m SimpleHTTPServer

---
_Source: https://npm.io/package/docindex · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._