thomasreinecke / git-playbook Goto Github PK

GIT Playbook is a documentation framework that allows you to create Documentation for your project using Markdown and GH-Pages rapidly

Home Page: https://medium.com/@thomas.reinecke/create-compelling-documentation-with-github-pages-16e4149efe9e

License: MIT License

JavaScript 49.33% HTML 4.17% Vue 29.91% SCSS 16.60%

github-pages documentation cms vuejs

git-playbook's Introduction

GIT Playbook

GIT Playbook is a documentation framework that allows you to create Documentation for your project using Markdown and GH-Pages rapidly. This is the repository for Medium article Create compelling Documentation with Github Pages by Thomas Reinecke and Kai Wedekind.

Main Features

Runs your Markdown-based documentation on a webapp
Mobile ready, responsive design
supports any level of document hierarchy
supports title, description & icon for every Folder & Document
Live Search/Filtering capability keyword and topic-based (no server infrastructure necessary for it)
All-In-One WebFrontend, only needs a webcontainer to run, optimized for deployment on GH Pages
Left-Sided Tree Navigator
Support for Multiple Playbooks in one app
Breadcrumb Support to navigate through any level of the document hierarchy easily
Topic Support to group documents together

How to use it

get started by reading the article Create compelling Documentation with Github Pages
clone repository and follow the "Build Setup" instructions below
edit "src/pageConfig.json" and change the document structure as you desire
write your documents in Markdown and put them into the "static" folder
create yourself a GIT repository and import your playbook trunk
deploy it with npm run gh-pages
in your GH repository > Settings > scroll down to "Github Pages", make sure it points to your "gh-pages" branch
find the link to your GH page deployment on that screen aswell
for feedback, enhancement requests or defect reports use "Issues" here on this repo

Enjoy!

Build Setup

# install dependencies
npm install

# serve with hot reload at localhost:8080
npm run dev

# build for production with minification, also build the search index
npm run build

# build the search index only
npm run build-search

# build for production and view the bundle analyzer report
npm run build --report

# run unit tests
npm run unit

# run e2e tests
npm run e2e

# run all tests
npm test

# deploy playbook to GH pages (includes build and deploy to GH pages)
npm run gh-pages

git-playbook's People

Contributors

Stargazers

Watchers

git-playbook's Issues

Is there anything specific to look after if I will use GitLab instead of pages?

Can this be deployed to GitLab?

How do add a new card with new SVG?

Some instruction/documentation on what elements you need to change for this will be really useful.

Numbered list - No number showing

I have tried using '1.' to make a numbered list but the numbers won't show.

npm run build fails "Cannot find module .\Playbook\build\build.js" in Windows 10

After doing a fresh clone of the repo in Windows 10, with current node versions 10.14.1 LTS and 11.3.0 the npm run build cmd fails with following messages:

PS C:\Users\lfreeman\testGitPlaybook> npm run build

[email protected] build C:\Users\lfreeman\testGitPlaybook
node build/build.js; node build/build.search.js

internal/modules/cjs/loader.js:582
throw err;
^

Error: Cannot find module 'C:\Users\lfreeman\testGitPlaybook\build\build.js;'
at Function.Module._resolveFilename (internal/modules/cjs/loader.js:580:15)
at Function.Module._load (internal/modules/cjs/loader.js:506:25)
at Function.Module.runMain (internal/modules/cjs/loader.js:741:12)
at startup (internal/bootstrap/node.js:285:19)
at bootstrapNodeJSCore (internal/bootstrap/node.js:739:3)
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] build: node build/build.js; node build/build.search.js
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the [email protected] build script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR! C:\Users\lfreeman\AppData\Roaming\npm-cache_logs\2018-12-05T15_03_40_671Z-debug.log

Deploying playbook to GitHub enterprise shows blank screen when loading

Went through build setup instructions using unmodified code. Can execute 'npm run dev' and runs locally ok. Unit and e2e test failed with "playbook" <> "Git Playbook" error message.
Can execute 'npm run gh-pages' but when attempting to load it shows a blank screen. Viewing page source shows it has loaded page with "This is your fallback content in case JavaScript fails to load". Repo named 'git-playbook'.

Hidden Pages

I would like to have an md file that is given a route ( i.e. .../meetings/minutes/2019-12-04 with a markdown file .../2019-12-04.md) but not have it show up as a tile or sidebar ( being indexed for search would be a nice to have ).
Conceptually as if there was a "hidden": "true" in pageConfig.json

Any direction on how I might accomplish that? Thanks.

Error: Loading chunk 0 failed for content display

All the nav in your template project appears correctly when deployed to a prod site; however, the content areas do not. Below is the error.

    at HTMLScriptElement.r (bootstrap 0337016ea0a643c5e87a:103)
c @ vue-router.esm.js:1905
12:36:22.434```

ERROR - Resolved in ./src/pageConfig.json

Running npm build output with successful build:

ERROR in ./src/pageConfig.json
Module build failed: SyntaxError: Unexpected token { in JSON at position 2318
at JSON.parse ()
at Object.module.exports (C:\Users\blablabl_user_name\Desktop\git-playbook-master\node_modules\json-loader\index.js:3:49)
@ ./src/services/configManager.js 3:0-44
@ ./src/router/index.js
@ ./src/main.js

In the file:
module.exports = function (source) {
if (this.cacheable) this.cacheable();
var value = typeof source === "string" ? JSON.parse(source) : source;
value = JSON.stringify(value)
.replace(/\u2028/g, '\u2028')
.replace(/\u2029/g, '\u2029');
return module.exports = ${value};
}

RESOLVED by reinstalling

License or attribution?

@thomasreinecke I love the Git Playbook implementation. I don't see any attribution or licensing information in the project's current master, and I would like to at least add a "powered by" footer link. Do you have a preference for how to add this?

I currently have a PR open at OpenAPITools/openapi-generator#1614 which uses Git Playbook and example output.

Typing in search box is missing keystrokes when search results are updating

I try to type in "how to go from here" and it misses a few of the letters:

Scripts assume reponame is git-playbook

It looks like there is a hardcoding of the repo name "git-playbook" in the scripts. I'm liking the way this project lays out things much better than other GH template engines. The repo name should be passed in when generating the site or something configurable.

I'm not a Front-end dev, but I'll see if I have time to contrib back something that does this.

node-sass update

For Node v11 the dependency on node-sass needs to be updated to "node-sass": "4.11.0". I can fork and make a pull request if you wish.