Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/xvxx/deadwiki

☠️ dead simple personal wiki
https://github.com/xvxx/deadwiki

cli markdown vial web wiki

Last synced: about 1 month ago
JSON representation

☠️ dead simple personal wiki

Host: GitHub
URL: https://github.com/xvxx/deadwiki
Owner: xvxx
License: mit
Archived: true
Created: 2020-05-10T18:30:24.000Z (over 4 years ago)
Default Branch: master
Last Pushed: 2022-01-05T18:41:29.000Z (almost 3 years ago)
Last Synced: 2024-10-07T20:08:36.206Z (2 months ago)
Topics: cli, markdown, vial, web, wiki
Language: Rust
Homepage:
Size: 1.11 MB
Stars: 61
Watchers: 4
Forks: 6
Open Issues: 2
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Awesome Lists containing this project

awesome-starred - xvxx/deadwiki - ☠️ dead simple personal wiki (web)

README

        

# RIP deadwiki

A fun project that I used almost constantly in 2020, deadwiki was an 

experiment in organizing information,

[developing a web library](https://github.com/xvxx/vial),

and creating a [weird web language](https://github.com/xvxx/hatter).

It is now abandoned and archived. Thanks for all the PRs!

---

# deadwiki

**deadwiki** is a Markdown-powered wiki that uses your filesystem as

its db. This means you can keep your wiki in a git repository and edit

content with your text editor, or read and modify pages `with style`

using its 1990s-era web interface.

---

There are two built-in ways to access your deadwiki:

- Run the local webserver and use the (minimal) HTML UI.

- Just use your filesystem. Regular Markdown files. `cat`, `ls`, etc.

## ~ status ~

Under construction!

_The git `master` may be broken, so make sure you install from

crates.io (see below)._

I use it every day, and I like combining it with other small tools. I

keep a Markdown TODO list in `~/.todo` that I manage on the command

line with a `todo` program, and I have a little scratch pad in

`~/.scratch` that I add links to in a shell using an `s` program,

like:

    $ s https://git.coolstuff.com/some/repo

With deadwiki, I symlinked both of those files into my `~/.deadwiki`

dir and can browse them using a fancy, 1990s-era HTML interface.

## ~ installation ~

Okay, so how do you get started? You just need `grep`, which you

probably already have, and [cargo], which is usually pretty easy to

install.

Once you've got both of them you can install it with:

    cargo install deadwiki

That'll give you a handy dandy `dead` CLI tool, if everything is setup

and `~/.cargo/bin` is in your `$PATH`. You should now be able to run

`dead -h` to see the possibilities.

## ~ getting started ~

To begin, create an empty directory or find one already populated with

`.md` files. This is your deadwiki. Simply point the CLI utility at it

to get going:

    $ dead my-wiki-dir/

    -> deadwiki serving my-wiki-dir/ at http://0.0.0.0:8000

Now visit http://0.0.0.0:8000/ in your browser!

By default the main page will list all your wiki pages, but if

`index.md` exists in your wiki it'll show that wiki page instead.

You can edit wiki pages locally with something like `vim`, or by using

the web UI. Edits show up on the next page load, as do new pages -

there is no database and no fancy pantsy caching. Just you, your

filesystem, and a dream.

In addition to [CommonMark], Markdown files can link to each other by

putting the `[Page Name]` in brackets. Like most wikis, it'll either

be a link to the actual page or a link to create it.

deadwiki also includes support for `#hashtags`. Any hashtag appearing

in wiki text will be linked to a search page that lists all wiki pages

containing that hashtag.

Finally, if you want to sync your wiki automatically, there is some

_very basic_ git support. Basically, if you start the `dead`

program with the `-s` or `--sync` flag and point it at an existing git

repository, it'll do this every 30 seconds or so:

    git add .

    git commit -am update

    git pull origin master

    git push origin master

Like I said, super basic! But it works, and it's nice that it syncs

changes you make even outside of the web UI.

## ~ keyboard shortcuts ~

There are two modes: browsing and editing. Editing is powered by

[SimpleMDE] and includes all its default shortcuts (shown below), plus

a few deadwiki-specific shortcuts.

Browsing mode includes a few keyboard shortcuts to make navigation

quicker and more nimble.

### Browse Mode

| **Shortcut**   | **Notes**                    |

| -------------- | ---------------------------- |

| `Double Click` | Enter edit or create mode    |

| `Ctrl-h`       | Go to the home page          |

| `Ctrl-j`       | Jump to page (fuzzy finder)  |

| `Ctrl-n`       | Go to the "new" page         |

| `Ctrl-e`       | Open editor for current page |

| `i`            | Insert mode: Edit or New     |

### Edit Mode

| **Shortcut**  | **Notes**                |

| ------------- | ------------------------ |

| `ESC`         | Exits edit mode          |

| `Ctrl Enter`  | Submits your edits       |

| `Cmd Enter`   | Same                     |

| `Cmd-'`       | Toggle Blockquote        |

| `Cmd-B`       | Toggle Bold              |

| `Cmd-E`       | Clean Block              |

| `Cmd-H`       | Toggle Heading (Smaller) |

| `Cmd-I`       | Toggle Italic            |

| `Cmd-K`       | Draw Link                |

| `Cmd-L`       | Toggle Unordered List    |

| `Cmd-P`       | Toggle Preview           |

| `Cmd-Alt-C`   | Toggle Code Block        |

| `Cmd-Alt-I`   | Draw Image               |

| `Cmd-Alt-L`   | Toggle Ordered LIST      |

| `Shift-Cmd-H` | Toggle Heading (Bigger)  |

| `F9`          | Toggle Side-By-Side      |

| `F11`         | Toggle Fullscreen        |

## ~ hacking ~

The code is in pretty rough shape right now, as this is mostly a

prototype-in-progress. But you can hack on it pretty easily with

[cargo]:

    $ git clone https://github.com/xvxx/deadwiki

    $ cd deadwiki

    $ cargo run wiki/

There's a basic wiki included that shows off some features.

## ~ future features ~

- `--read-only` mode, so i can have a copy i can view anywhere

- mobile-friendly CSS

- search (probably just `grep`)

- `--gopher`: serve wiki pages over gopher too (probably using [phd])

- `*.css` in wiki dir gets included

- homebrew package, AUR package

- `brew services` for running on osx, `systemd` for arch

- basic TUI for creating new pages or opening wiki pages in `$EDITOR`.

## ~ philosophy ~

- no database

- text editor/plain text friendly

- prefer server-side rendering

- take your data with you (scm friendly)

- lean on standard UNIX commands (find, grep)

- js only for user input (keyboard shortcuts, markdown editor, finder)

- no js frameworks/helpers

- build time matters (28 crates currently, ~6s release ~4s debug)

## ~ screenies ~

| ![screenie1](/assets/img/screenie1.jpeg) | ![screenie1](/assets/img/screenie2.jpeg) |

| :--------------------------------------: | :--------------------------------------: |

|        Rendering Markdown. `Wow.`        |       Editing Markdown. `Amazing.`       |

## ~ bug reports ~

Please direct all known and unknown (suspected) bugs to this URL:

- https://github.com/xvxx/deadwiki/issues/new

## ~ credits ~

All SVG icons are Feather icons: https://feathericons.com/

deadwiki's source is licensed under the [MIT License].

[cargo]: https://rustup.rs

[simplemde]: https://simplemde.com/

[keys]: https://github.com/sparksuite/simplemde-markdown-editor#keyboard-shortcuts

[commonmark]: https://commonmark.org/

[phd]: https://github.com/xvxx/phd

[mit license]: https://opensource.org/licenses/MIT