Clarify the Instructions

[twMat]

@kookma - thank you very much for this.

Here is my attempt to try it out, documenting my fumblings with the hope of improving the instructions (the README.md and the tiddler Tiddlywiki and GitHub Saver) and the procedure so that any TW user can do this with ease for a "Tiddlyspot alternative".

The biggest problems come from steps and assumptions that the instructions take for granted, thus:

First; It is not obvious that the demo is actually the instructions and that one should not download any "plugin", which is how one usually "extends" TW. IMO this should be noted in the README.

...but, after this, there's the immediate hit of the brick wall along with the all familiar feeling of hopelessness with github:

The Tiddlywiki and GitHub Saver tiddler, under "Setup GitHub repository" states:

If your index.html is going to be located in root directory of your repository, then use master branch as the source of GitHub pages
If the index.html is located in docs folder or wikis folder or other folder of choice, then select master branch/docs folder or master branch/wikis folder

Does my hope for a "tiddlyspot alternative" mean I will want multiple repositories or one repository with multiple "wikis folders"? I'm guessing the second (since it's called "wikis") but this needs clarification in the instructions.

...but then, what is a "wikis folder"???

And to Activate GitHub pages>"Choosing a publishing source", there is some gh instruction that I should choose a publishing source via (step 3) "None or Branch" or (step 4) select a "folder"... and I'm guessing I should select a "folder" because of the mention of "wiki folders"... but no "folders" options show up in my gh settings UI:

What to do?

Thank you.

[kookma]

Hi @twMat - Thank you for your comments. I will improve the instruction and will include your suggestion.

Have you followed step ii and have you set up the gh pages successfully? Please see step 2 of instructions https://kookma.github.io/TW5-GitHub-Saver/#Tiddlywiki%20and%20GitHub%20Saver

[kookma]

@kookma - thank you very much for this.

Thank you @twMat .

Here is my attempt to try it out, documenting my fumblings with the hope of improving the instructions (the README.md and the tiddler Tiddlywiki and GitHub Saver) and the procedure so that any TW user can do this with ease for a "Tiddlyspot alternative".

The biggest problems come from steps and assumptions that the instructions take for granted, thus:

First; It is not obvious that the demo is actually the instructions and that one should not download any "plugin", which is how one usually "extends" TW. IMO this should be noted in the README.

...but, after this, there's the immediate hit of the brick wall along with the all familiar feeling of hopelessness with github:

The Tiddlywiki and GitHub Saver tiddler, under "Setup GitHub repository" states:

If your index.html is going to be located in root directory of your repository, then use master branch as the source of GitHub pages
If the index.html is located in docs folder or wikis folder or other folder of choice, then select master branch/docs folder or master branch/wikis folder

Does my hope for a "tiddlyspot alternative" mean I will want multiple repositories or one repository with multiple "wikis folders"? I'm guessing the second (since it's called "wikis") but this needs clarification in the instructions.

Yes, you are right you can set up a folder and use it as a repo for several Tiddlywiki files.

...but then, what is a "wikis folder"???

You can create a folder for yourself, I just used this name to indicate it keeps Tiddlywiki files in one place. You can use any name you like.

And to Activate GitHub pages>"Choosing a publishing source", there is some gh instruction that I should choose a publishing source via (step 3) "None or Branch" or (step 4) select a "folder"... and I'm guessing I should select a "folder" because of the mention of "wiki folders"... but no "folders" options show up in my gh settings UI:

What to do?

I think it is enough to activate the gh pages. Then you can see the option to choose a branch and a folder. One issue here is GitHub has changed its master branch to main branch, so I have to correct it.

Thank you.

Please let me know if you have any problem.

[kookma]

Hi @twMat - Thank you for your comments. I will improve the instruction and will include your suggestion.

Have you followed step ii and have you set up the gh pages successfully? Please see step 2 of instructions https://kookma.github.io/TW5-GitHub-Saver/#Tiddlywiki%20and%20GitHub%20Saver

@twMat - Sorry I closed this by mistake.

[twMat]

Thanks for follow up, @kookma . I will look closer at this in the coming weekend.

If you have the possibility to record screen videos, I'm sure all steps would be substantially simpler. In a video you can, in 2 seconds, show "click this button" but in text it needs to say "scroll down in the repository to the OAUTH setting and select the X alternative" etc. If this all was knowledge to understand then it makes sense with text but for just a one time set-up, a video makes much more sense :-)

[kookma]

I will look into it to prepare a short clip.