So, you want to write your own hints for a game? That's cool. Every game should have spoiler free hints! Best place to start is this template repository. It has examples and the following instructions.
Fill this README.md with something you want to tell _a contributor_. This README is not shown in the www.nicegamehints.com site.
Copy this template repository (From the green "Clone or download" button) to get started with your own game hints.
The concepts for the NGH hints are a game that contains multiple guides. A guide has multiple hints that the reader can then reveal one by one. A guide can also have subguides.
Guide files are written using markdown language.
The one required file is index.md. This file defines the name of the game and other metadata for the game. Example index.md looks like this:
---
title: Deponia Doomsday
keywords: deponia doomsday, guide
author: Juho Rutila
praise: https://www.buymeacoffee.com/jrutila
---
Welcome to free hints for Deponia Doomsday! Select a guide.The part between --- lines is metadata:
- title: The name of the game that is shown in the page and page title etc.
- keywords: list of keywords to help search engines, these root index.md keywords are repeated on every other guide under the game
- author: Your name. Shown under every guide.
- praise: buymeacoffee.com url to ask readers to give you money for your hard work with the guide.
The rest of the text is markdown shown in the first page of the guide.
A guide file is just a md file containing the hints with headers. Example of a guide file:
---
title: How to get tin foil?
keywords: tin foil, baked potato
---
This text is shown first to the reader and it is also visible in Google snippet.
# Show the first hint
Everything until the next `#` line is part of the first hint. You can use markdown notations.
# Show the second hint
This is the contents of the second hint. Here is a picture:
## Tell me the solution
The two hashtags means that this text will contain spoilers. The button is rendered red so that the reader knows to watch out.Again, the guide file starts with mandatory metadata:
- title: Title of the guide shown in the subguide buttons and as the page title for example in Google listings
- keywords: list of keywords to help search engines
The following text is shown to the user straight away so don't give up the solution here yet! It is also shown in Google's listings as they have a preview of the page. The actual hints are not shown in Google.
Every # line (markdown's header) denotes one hint under the guide. That text is shown in the hint button so don't make it too long. It can be as simple as "Hint 1", "Hint 2" etc.
Every '##' line denotes a hint that will reveal a spoiler next. These hints get special treatment in the UI.
You can use basic markdown notations: https://guides.github.com/features/mastering-markdown/
If you want to display a picture as part of the guide, use this markdown: 
The named picture should be inside the same folder as the guide file.
NGH Editor Just write the markdown and the editor lets you upload the picture then. It handles the renaming of the picture file automatically.
Guides form a folder structure. All the folders and md files under the guide's folder form the subguides. Under the guide folder a index.md file is required. Example of guide folder structure:
📦 repository root
┣ 📜 index.md
┣ 📂 first-part-of-the-game
┃ ┣ 📜 index.md
┃ ┣ 📜 subguide.md
┃ ┗ 📂 subguide-for-first-part
┃ ┗ 📜 index.md
┣ 📂 second-part-of-the-game
┃ ┣ 📜 index.md
┃ ┣ 📜 another.md
┃ ┗ 📜 benother.md
The file name is only visible in browser location bar and some other places.
Subguides are listed by the order metadata. It will then order the sub guides from lower number to higher. If you omit the order metadata the guides are listed in alphabetical order. For example if you want to order the benother.md before another.md:
filename: another.md
---
title: Second item
order: 50
---filename: benother.md
---
title: First item
order: 20
---To link to another guide you write markdown's links. Link with the single word of the guide filename. This means the guide file names should be unique. Here is an example guide file.:
---
title: How to get tin foil?
---
Guide for tin foil.
# Show the first hint
First, you need [a hot potato](potato). This will link to another guide file that is in the same folder as the guide file.
# Show the second hint
Next, you need [a potato peeler](../potato-peeler/index.md). This will link to another subguide that is in parent folder. Prefer to use the single word link.
# Show the third hint
Finally, get [a permission to peel](/fourth-part-of-the-game/permission.md). This will link starting from the root of the guide folder structure. Prefer to use the single word link.To link to another guide's certain hint you write markdown's links with anchors. Here is an example target guide file.:
---
title: Linked hints
---
Intro
# First hint
This is the first hint and needs to be skipped
# Second hint {#second}
This is the second hint we want the reader to get directly
To link directly to the second hint:
---
title: How to get tin foil?
---
Guide for tin foil.
# Show the first hint
Go to the [other guide's second hint](guide#second). This will link to another guide file's second hint.
You can write quick hints inside a guide file. A quick hint is rendered as a question mark button that will show the hint in a popup.
Write quick hint with the markdown footnote notation: ^[ footnote notation ]
---
title: Example about quick hint
---
In this hint you should use some eating utensil. ^[ You can find a fork in the kitchen drawer. ]
# I have a tool
The fork? Be careful with it. ^[ Stick the fork into the electric outlet. ]
# Show me
Click on the right question mark to see a picture. ^[  ]Signposts are direct quotes from the game that might help the player with the puzzle. They are hidden from view until the user opens the signpost collapse. Signposts are added in the beginning of the hint file. Like this:
---
title: Example of signposts
---
> Character: This is a text from the game
> Another character: add an empty line if there are multiple signposts
Here is the actual text that is shown to the user. The above signpost texts are hidden, at first.
# First hint
And the first hintYou can also show a link in the subguide list that will point to another guide file.
---
linkTitle: This is a subguide linking to another guide
link: /full/path/to/guide.mdYou can create a special folder with a name of _achievements to write gradual hints for achievements. These _achievements folders can be under any folders. I suggest to write them into the root folder or under the chapter folders of the game.
📦 repository root
┣ 📜 index.md
┣ 📂 first-hints
┃ ┣ 📜 index.md
┃ ┣ 📜 subguide.md
┣ 📂 _achievements
┃ ┣ 📜 index.md
┃ ┣ 📜 im-ready.md
┃ ┣ 📜 im-ready.png
┃ ┣ 📜 did-that.md
┃ ┣ 📜 did-that.png
In above example there are two achievements: im-ready and did-that. The png file is a small image of the achievement that is rendered on the achievement list. The achievement files are pretty much similar to hint files. On top of other metadata you should also write a subtitle. It will be shown to the user in the achievement list.
You can have direct linking from a guide to the achievement. Many times the achievements are related to specific puzzle or area in the game. You can link to the achievement by adding a achievements metadata like this:
---
title: This awesome area
achievements: im-ready,did-that
order: 50
---You can add a file named background.webp in the root folder of you guide. That image will be used as the background image of the guide.
You can add a file named small_bg.jpg in the root folder of you guide. That image will be used as the background image in the listing. It has to be 500x300 jpg.
Browse the Nice Game Hints repository for examples. The Deponia guides are great to start with!
You can test your written guide in www.nicegamehints.com. First you have to have the guide in a local directory structure. This probably is the case if you are writing it locally. Next, you need to serve the directory via http.
You have three options:
Just run docker-compose up -d, it will load an image and run it
on Windows:
docker run --rm -p 8080:8080 -v /$(pwd):/site ghcr.io/nice-game-hints/ngh-serve:latest
on Linux:
docker run --rm -p 8080:8080 -v .:/site ghcr.io/nice-game-hints/ngh-serve:latest
Install http-server (https://www.npmjs.com/package/http-server) with npm install -g http-server
After installing the http-server go to the root of your guide (where the README.md and index.md are) and run:
http-server --cors -d true -c-1 .
It should output something like this:
Starting up http-server, serving .
Available on:
http://192.168.64.1:8080
http://180.97.36.27:8080
http://127.0.0.1:8080
Hit CTRL-C to stop the server
Please note the port of your http-server (in the example it is 8080).
You can test if the http-server is working by navigating with your browser (note the port number) to http://localhost:8080/index.md. You should see your raw index file.
If the http-server is running properly and you see the file, you can now try to navigate to address http://www.nicegamehints.com/guide/local:8080/ (please note the port number).
Adjust your cookies (disable all but required) to see the guide in pure form. The navigation might be having issues (especially when navigating back). Please check the url and remove excess "/" characters if you end up in a 404 page.
Please create an issue to this repository about publishing and I will help you with it.