# *Note that this is a work in progress* All offers of assistance (even just to test, especially on Android pads or phones) gratefully received. *BWM 2026-06-19* # Overview of how it works The Wiki is comprised of files formatted in [Markdown](https://en.wikipedia.org/wiki/Markdown). It runs on [Obsidian](https://obsidian.md), using an [Obsidian Publish](https://obsidian.md/publish) subscription. - The base Markdown files and attachments are held in a [GitHub repository](https://github.com/hobart-hackerspace/wiki-obsidian). - The published form is hosted on an [Obsidian website](https://publish.obsidian.md/hhs-wiki/Hackerspace+Wiki), with a reverse proxy link from our domain name [wiki.hobarthacker.space](https://wiki.hobarthacker.space/hhs-wiki/Hackerspace+Wiki). ## Obsidian - [Obsidian](https://obsidian.md) is a personal note-making tool that is free, stores its information locally and runs on all major platforms (Android, iOS, Linux, MacOS and Windows). - You can use Obsidian for free for yourself. It’s also free to use to contribute to our wiki, although you do have to register as a user. - We use an additional paid licence of the *Obsidian Publish* product to generate and host our wiki pages, - Obsidian stores all its text information in [Markdown](https://help.obsidian.md/syntax) format. This is an extremely readable plain text format that makes documentation easy. The Obsidian markdown editor is especially easy to use. ## The repository - All markdown source and assets (images etc) are stored in and shared from a [GitHub](https://github.com/hobart-hackerspace/wiki-obsidian) repository. - The GitHub repository is public, so anyone can read from it or clone it. Only authorised members can make changes to it, but anyone is free to suggest changes, via the GitHub Pull Request mechanism. # Pre-requisites. You’ll need to ensure all the [Wiki contribution pre-requisites](Technical/Wiki%20contribution%20pre-requisites.md) are in place. It’s a bit of a fiddle, but fortunately you’ll only have to do it once:-) # The repository You’ll need to connect to and clone the repository - The repository is at [github.com/hobart-hackerspace/wiki-obsidian](https://github.com/hobart-hackerspace/wiki-obsidian) - Make a local copy of the repository by cloning it. - On a laptop or desktop, use your chosen `git` tool to clone the repository into a workspace directory. - If you want to be able to push your contributions directly to the repository, you’ll need to be added to the Hackerspace Github group. - Send a note to [email protected] asking to be added as a user to the members list. - Alternatively, you can suggest changes by creating a “Pull” request. ## Repository branches *Git* is a software development tool . As such, it allows multiple branches in the “evolutionary tree” of the source code. For day-to-day stuff, we keep it simple; there is just a single “normal” branch, entitled `main`. This is the branch that tracks the current visible state of the Wiki. # Making contributions ## Your Obsidian vault Make the cloned directory into an *Obsidian* vault. - Open *Obsidian* and go to “Manage Vaults” - See the [relevant Obsidian Help](https://help.obsidian.md/vault) for details - You may choose whatever name you like for the vault - it will be local to you. ## Work in your local copy of the repository 1. Use your favourite `git` tool to push to & pull from the repository - See [Wiki contribution pre-requisites](Technical/Wiki%20contribution%20pre-requisites.md#4.%20*Git*) 2. Do a `pull` from the repository to ensure your copy is fully up to date. 3. [Optional]: 1. If you’re [making major changes](#Making%20major%20changes%20[optional]), make a new personal branch from this and check it out. 2. Or, if you already have a personal branch, merge the current state of `main` into it. ## Open the vault in *Obsidian* Make your contributions (additions and/or changes). - Note that Obsidian has two ways of displaying pages: reading and editing. Within editing mode there are a further two modes: “Live preview” or “Source mode” (settable from the “Options” gear wheel icon). - “Live preview” is a WSIWYG editor similar to *MS Word*. Use the right-click options menu to format, add links, etc. This is the mode to use if you are used to *Word* or similar tools. - “Source mode” is what it says — you see the whole page as Markdown source code. You may find that more convenient, if you’re familiar with Markdown. - The [*Obsidian* Formatting Help pages](https://help.obsidian.md/syntax) have lots of advice on how to format your contributions. - Use the other existing pages as models for consistent page structure, image formatting, table formatting, source code contributions etc. ## *Publish* your changes to see how they look When you’re happy with your contributions: 1. [*Publish* them](https://help.obsidian.md/publish/setup#Open+Publish) - Ensure that you’re [logged in to *Obsidian*](https://help.obsidian.md/publish/setup), so that *Publish* will work. - If you have any pages that have attachments (for example images or attached PDFs), ensure that you click on `Add linked` at the top of the **`Publish`** panel, so that the attachments get published along with their host pages. 2. Check the page formatting on [the wiki website](https://publish.obsidian.md/hhs-wiki/Hackerspace+Wiki) 3. Make any adjustments and re-publish 4. Refresh the page to see the new content. You may have to do a [“hard refresh”]( https://www.wikihow.com/Force-Refresh-in-Your-Internet-Browser) to clear the browser cache. - Note that some part of the *publish*→*web browser*→*browser cache* sequence seems to have limits on how frequently you can refresh a page. - Sometimes if a page takes a few goes to get the published details right, you won’t see a change when viewing in your browser, even if you do a hard refresh. - Try a different browser or take a coffee break. ## Check your changes in If that’s all ok, check the changes into your branch 1. Please use appropriate useful comments. - If you’ve done a range of alterations, feel free to check in batches of changes with different comments for each batch . 2. If you made some experimental changes that you don’t want to keep, *revert* them with your `git` tool, so that ‘git status’ shows nothing outstanding. 3. Push your committed changes to the GitHub repository. 4. If you’re [working in your own named branch](#Making%20major%20changes%20[optional]), checkout the `main` branch and merge your changes into it. 5. Push the merged `main` back up to GitHub. ## Have someone else proof them It’s always good practice to have someone else look over any changes. - We all occasionally have slips of the finger or the mind - There’s no loss of face in finding these early!! Then the entire cycle can start again… ## Making major changes [optional] If you’re making more than simple changes, we recommend that you set up your own named branch to make contributions. - Note that *Obsidian* will automatically work with whichever branch you have checked out, as the vault is just a directory and checking out branches simply changes the directory contents, not the directory itself. - You can then merge your branch with the `main` branch as needed. - If you already have a personal branch, merge the current state of `main` into it each time you go to make changes or new contributions. - Your named branch can be a workspace for you to try things, especially if your’e not sure how they will be rendered into HTML pages. - It makes much easier to fiddle around without disturbing the work that others have done. - Also, it’s far less likely that you’ll run into clashes when updating the repository.