Gollum calls this "overview".

When an error happens, it should be clear what the cause was and how the user can fix the problem. This includes both command ling error messages and error messages sent over HTTP.

• Error messages sent of HTTP should ideally look relatively nice. Like they should not be plain text; they should not be the output from a Debug trait impl.
• Do we have to worry about that thing where IE only displays error pages greater than 512 bytes in size? It looks like Chrome may have copied this feature
• Audit the different From implementations for MyError. Make sure the message matches the level of specificity of the error type they convert from.

Some specific cases that are known to not have good error messages:

• When a markdown file is not valid UTF-8.
• Failures to read wiki pages.
• Failure to find wiki pages.

Currently Smeagol uses hyper for HTTP and askama for templates. I assume more full featured web frameworks exist for Rust.

A non-exhaustive listen of reasons why a web framework might be useful:

• Built in form persistence.
• Perhaps the ability to have static type checking when constructing links to different controllers or pages

Another approach would be to only write an API in Rust and make a fancy JavaScript frontend.

When editing, it would be nice to preview what the output will look like. Markdown is pretty simple, but formatting mistakes can still be made and it doesn't feel right adding further commits to fix formatting errors.

Currently this program is designed to be used as an executable. It could also be accessible as an API, like how gollum-lib works.

• Figure out if it makes sense to have an API
• Design a Rust API
• Design an FFI-api
• Use the FFI-api to create a Ruby API that is a drop-in replacement for the Ruby gollum-lib.

The software should not waste resources wantonly. The following dimensions should be considered, very roughly in order of importance:

• Installation time
• Latency (time to first byte)
• Startup time (probably correlated with binary size)
• Binary size
• Memory usage
• Throughput (requests per second)

The software is currently intended to be used by a single user at a time, so throughput and scaling is not a huge concern.

Some concrete performance things to investigate:

• Render markdown into the template engine's buffer directly. That is, instead of rendering markdown into a string, and then feeding that into the templating engine, have the markdown render expose a Write that is called from the template system's Write implementation.
• Instead of rending templates into strings and then sending the contents over the wire, use the Write interface on templates to send directly to the socket. Some investigation will be required to see how much this change effects allocations and copying, as this may just shift the allocation from the template engine to the network abstraction.

Security is not a huge issue, as the current intended use case is a single person viewing data they wrote. However there are some things we should watch out for even in the single user case:

• Make sure by default we are only binding to localhost by default, so that the user's wiki is not exposed to other people on the network inadvertently.
• #43

Some other security issue could become an issue in a multi-user environment

• Path traversal. Ideally we could also use some OS sandbox like unvail(2) to help us ensure this works.
• XSS
• Sandboxing, using something like pledge(2) or SELinux

The webserver needs to be able to map file extensions to MIME types so it can set the correct value for Content-Type headers. This will be useful when serving media like pictures or when allowing binary files to be stored and downloaded from the wiki.

The wiki should be writable from the website. Features include:

• #16
• #51
• Some amount syntax highlighting?
• Maybe embed the VS Code editor into the page?
• Stretch goal that probably will never happen: a WYSIWYG editor

Use Tantivy to create an in-memory index on startup and allow searching it.

People should be able to discover Smeagol, understand it, and solve problems they encounter.

• Have a getting started guide
• Create a dedicated webpage that describes what problem this program even solves
• Create a man(1) page.

Cargo 1.59 should have an option for this:
rust-lang/cargo#10088

I switched to Smeagol-Wiki from deadwiki, which generated default indexes where there weren't any. So to avoid having to write dozens of Index.md files for a very dynamic wiki (I use it as a personal KMS), I wrote automation for the job. Available here: https://github.com/jrstrick/Make_Index-for-Smeagol-Wiki.

Thanks for making smeagol-wiki. It's been a godsend.

There are two ways I can think of to do this:

• Redirect back to the edit page with the modified content. Display an alert with the error message.
• Instead of submiting the form with the tradtional post, use JavaScript to save the changes. Once the client side confirms that the page was saved, only then redirect to displaying the page.

I think we could also save the edited page in localstorage, so if the browser crashes, the changes are not lost.

Currently it is being served from unpkg.com.

This might part of a larger theme of having a fancier front end story. Like we could download the CSS files from NPM and user and bundler and whatnot.

Currently we only index once on startup.

Support reading and writing files from a Git repository. This includes bare repos. Features include:

• #34
• #35
• #36
• Viewing file change history
• View overall wiki recent changes
• #39

The program should be easy to acquire.

• Automatic CI builds for every release
• #19
• No internet connection should be required after the program is downloaded #9
• #15
• Code signing
• macOS notarization?
• macOS fat binaries?
• #31
• #40

It would be cool if this program was easy to install using operating system packages managers. Here are a few:

• Debian packaging
• Homebrew packaging
• pkg-src packaging
• FreeBSD Ports packaging
• Nix packaging
• Windows packaging (Choco, winget, Windows Store, Scoop, etc.)

Note that currently winget does not support standalone executables

Currently half a megabyte of CSS is downloaded on every page view.

Ideally we could do something where we generate a URL for the static assets at build time that contains the hash of the file contents. This would make it easy to bust the cache when the file changes.

It should be easy to search for content in the wiki. Even basic searching is useful, but there is a lot that can be done to make the experience great:

• #23
• #41
• In search UI, update search results on every key press
• Support regex queries
• Consider persisting search index to disk. Currently it is in-memory and recreated on every startup.
• Speed up indexing. Currently it is a little slow when indexing tens of thousands of documents.

Both Windows and macOS have the capability to run AMD64 programs on ARM64. In light of that, the installer could fallback to AMD64 binaries if no ARM64 binaries are available.

On macOS, there are sysctls for finding our what type of the binaries the system natively supports.

On Windows 11, GetMachineTypeAttributes look interesting.

Presumably Tree.walk would be faster than the current method, which traverses from the root to every directory.

Some ideas are in the CLI book: https://rust-cli.github.io/book/tutorial/packaging.html

trust gets most of the way there. There are some tweaks I would like to make:

• Instead of using rustc to detect the target triple, steal the target detection code from the rustup-init.sh script
• Instead of parsing the message GitHub gives when doing a 302 redirect to find the the latest version, do something else. Either a lot of work to discover the latest version at download time, or include the version number in the install instructions.
• Add a PowerShell script for Windows users

Also, a cargo install command should be listed, so people can install on targets I have not yet create binaries for.

Some more pie-in-the-sky ideas:

• rustup already does a lot of what I want for binary distribution and installation. Perhaps a binary rust package manager could be built out of parts of it?

It might be helpful for customer support purposes to have a Git hash and version number easily accessible on the web page. And also in the --version command for that mater.

Also known as XSRF.

Gollum supports several markup languages. We could support some of theme:

• Markdown
• RDoc
• AsciiDoc
• Creole
• MediaWiki
• Org
• Pod
• ReStructuredText
• Textile

It only prints the "indexing files" message. It is listening though.

The latest release API is documented to return the most recent release based on creation time. This means that if I make a patch for an old version, that will now be considered the "latest version".

So install scripts need to get a list of versions and pick the one with the highest version number.