Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kataras/gitbook-to-wiki
Export your GitBook as a GitHub Wiki or Docsify pages.
https://github.com/kataras/gitbook-to-wiki
gitbook gitbook-to-wiki wiki
Last synced: 3 months ago
JSON representation
Export your GitBook as a GitHub Wiki or Docsify pages.
- Host: GitHub
- URL: https://github.com/kataras/gitbook-to-wiki
- Owner: kataras
- License: mit
- Created: 2020-08-09T02:34:01.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2020-08-09T15:13:07.000Z (over 4 years ago)
- Last Synced: 2024-06-20T12:50:54.369Z (7 months ago)
- Topics: gitbook, gitbook-to-wiki, wiki
- Language: Go
- Homepage: https://gitbook.com
- Size: 18.6 KB
- Stars: 13
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# GitBook to GitHub Wiki
[](https://travis-ci.com/github/kataras/gitbook-to-wiki) [](https://goreportcard.com/report/github.com/kataras/gitbook-to-wiki) [](https://pkg.go.dev/github.com/kataras/gitbook-to-wiki)
This CLI tool was initially created to generate the [Iris Wiki](https://github.com/kataras/iris/wiki). Works with the latest https://gitbook.com as of **2020**.
GitBook is the best tool on writing & publishing markdown books. They have an excellent support team and they do offer premium plans for Free and Open Source Projects (I have seen it myself!).
## Installation
The only requirement is the [Go Programming Language](https://golang.org/dl).
```sh
$ go get github.com/kataras/gitbook-to-wiki
```
By navigating to the [Releases page](https://github.com/kataras/gitbook-to-wiki/releases) you can also **download the executable file** for your operating system. Note that, the $PATH system environment variable should contain an entry of the `gitbook-to-wiki` program you have just downloaded. Alternatively, copy-paste the `gitbook-to-wiki` executable to the current working directory.
## Getting Started
Navigate to the parent directory of your gitbook, e.g. `/home/me`.
Clone your repository's wiki:
```sh
$ git clone https://github.com/$username/$repo.wiki.git
```
The directory structure should look like that:
```
│
└───$repo.wiki
| .git
| Home.md
└───$gitbook
| SUMMARY.md
├───subdir
| ...other files
```
Open a terminal window and execute the `gitbook-to-wiki`:
```sh
$ gitbook-to-wiki -v --src=./$gitbook --dest=./$repo.wiki --remote=/$username/$repo/wiki
```
Push your changes to the `master` branch of your `$repo.wiki`:
```sh
$ git add .
$ git commit -S -m "add new sections"
$ git push -u origin master
```
Navigate to and you should be able to read your GitBook as GitHub Wiki. Congrats, that's all!
## How it works?
1. Unescapes `\(should be unescaped\)` to `(should be unescaped)` (when you push GitBook's contents to a GitHub repository it automatically adds those escape characters)
2. Handles page references (`{% page-ref page="../dir/mypage.md" %}`)
3. Copies code snippets **untouchable** (that's trivial but important because older tools I've used reported and stopped the parsing because of a simple HTML code snippet!)
4. Handles **asset links**, both absolute(http...) and relative, e.g. ``
5. Handles **section links**, e.g. `[page title](relative.md)` to `[[page title rel|relative]]`
6. Handles **sub directories and sub sections**, e.g. `responses/json.md` to `responses/responses-json.md` (so GitHub Wiki can see it as unique, as it does not support sub-directory-content).
7. Handles `SUMMARY.md` to `_Sidebar.md`, it is not just a simple copy-paste, a content like that:
```md
# Table of contents
* [What is Iris](README.md)
## 📌Getting started
* [Installation](getting-started/installation.md)
* [Quick start](getting-started/quick-start.md)
```
Is translated to:
```md
* [[What is Iris|Home]]
* 📌Getting started
* [[Installation|getting-started-installation]]
* [[Quick start|getting-started-quick-start]]
```
8. And, of course, the `.git` directory is not copied or touched at all.
Don't hesitate to ask for more features. This tool works for the Git Book of a 18k starred project's documentation but if I missed something please [let me know](https://github.com/kataras/gitbook-to-wiki/issues/new).
## License
This software is created by [Gerasimos Maropoulos](https://twitter.com/MakisMaropoulos) and it is distributed under the [MIT License](LICENSE).