General > General Technical Chat
Documenting projects to the web
(1/1)
NivagSwerdna:
I have quite a few hobby projects and the documentation for this is spread around my files... I've been thinking of organising this into a kind of journal that was subdivided by projects... so a top level and then each project has diary entries and resources etc.
I would also like to share this info so the world can know what a complete genius I am. ;)
Any suggestions?
I was thinking that I need a tool that is easy to use locally so that I can build up the content easily... e.g. drag and drop of images would be nice
The actual updating of the public version could be done periodically and does not need to be instantaneous
ebastler:
Provided that you have some web server space available somewhere (maybe included with your internet access package anyway?), I can recommend Hugo, a static website generator.
I chose it since I did not want to depend on some hosted build-your-homepage toolkit (like wix.com), and neither did I want the responsibility of hosting some active content management system (like Wordpress) myself, with constant security patches etc.
Hugo is a tool which runs locally (offline) on your computer. The input you provide is a folder hierarchy with Markdown files (easily written in any text editor, and nicely human-readable), plus whichever files and pictures you want to include. The page layout is defined by a set of Hugo templates and a CSS file, jointly called a "theme". A large library of sample themes is available, but you can also adapt these to taste or craft your own.
The process is not exactly drag & drop, but straightforward: Make your updates to the input files (via your favorite text editor), run Hugo to generate an output folder structure (static HTML files plus images etc.). Look at a local preview via Hugo's built-in local web server, edit and repeat if needed -- once you are happy with the changes, upload the output folder structure to your external web server.
For my own website, www.e-basteln.de, I did not want a blog-style structure, but preferred a hierarchy of topics. But many themes specifically suited for blogs or journals are also available on the Hugo site.
I hope this will be a future-proof solution, since the content format, i.e. the Markdown language and folder structure, is not proprietary. It is also "fire and forget": During periods where you do not want to post new content, you don't have to worry about new security issues and attacks. I have used Hugo for the past four years and am happy with it.
EDIT: If you are not particular about the layout and just want to archive and publish your projects, github might be an alternative. You are relying on Microsoft's service there, but become part of a very widely known repository -- and you get version management for free.
Picuino:
I recommend Sphinx: https://www.sphinx-doc.org/en/master/
static site generator, based on Python and ReStructuredText.
Is the software used for Python's documentation.
You can easily store your pages in Github and combine it with Read The Docs: https://readthedocs.org/
Edit:
Example page: https://docs.readthedocs.io/en/stable/tutorial/
Source on Github: https://raw.githubusercontent.com/readthedocs/readthedocs.org/main/docs/user/tutorial/index.rst
NivagSwerdna:
I have done some research and I think I am going to try Hugo and Docsy as a starting point. I can probably run that locally until I want to share and at that point might try Netlify.
It's not quite drag and drop but it might be a starting point.
tggzzz:
For organising my thoughts on a local machine - which isn't what you asked for - I like TiddlyWiki.
https://tiddlywiki.com/
https://classic.tiddlywiki.com/
--- Quote ---Welcome to TiddlyWiki, a reusable non-linear personal web notebook. It's a unique wiki that people love using to keep ideas and information organised. It was originally created by JeremyRuston and is now a thriving open source project with a busy Community of independent developers.
TiddlyWiki is written in HTML, CSS and JavaScript to run on any reasonably modern browser without needing any ServerSide logic. It allows anyone to create personal SelfContained hypertext documents that can be published to a web server, sent by email, stored in a Dropbox or kept on a USB thumb drive to make a WikiOnAStick. Because it doesn't need to be installed and configured it makes a great GuerillaWiki.
--- End quote ---
Navigation
[0] Message Index
Go to full version