Documenting projects to the web - Page 1
Forum section: electronics / general

author: NivagSwerdna
author_rank: Super Contributor
timestamp: June 20, 2022, 02:09:07 pm
content: 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 niceThe actual updating of the public version could be done periodically and does not need to be instantaneous

author: ebastler
author_rank: Super Contributor
timestamp: June 21, 2022, 06:18:55 pm
content: Provided that you have some web server space available somewhere (maybe included with your internet access package anyway?), I can recommendHugo, 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 largelibrary of sample themesis 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.

author: Picuino
author_rank: Super Contributor
timestamp: June 21, 2022, 06:51:01 pm
content: 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

author: NivagSwerdna
author_rank: Super Contributor
timestamp: June 23, 2022, 01:01:14 pm
content: 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.

author: tggzzz
author_rank: Super Contributor
timestamp: June 23, 2022, 01:36:25 pm
content: 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