Wiki

[Anuken]

This is a discussion issue for this card on Trello.

• What wikis have people made already?
• Which wiki provider looks the best and is easiest to use?
• Which wiki sites support easy autogeneration of pages?
• Can ads/paid wikis be avoided?
• Can we get away with a wiki on GitHub?

Pinging @Luxray5474 for input.

[skybldev]

Thanks for starting the issue and pinging me, I've been waiting a long time to actually get things going faster :P

What wikis have people made already?

There is a WIP 3.5/Classic Wiki on Wikia, and one for beta that TCEO, Sonnicon, Jibbyy (who Is inactive I think), and I have been and are (slowly) working on on GitLab. The latter has a roadmap thing that I am also trying to update regularly and as I make changes.

Which wiki provider looks the best and is easiest to use?

Many people have different opinions on this, most believe in Wikia to be the best, but I personally think that an mkDocs site that is visually simpler, albeit with a bit of a learning curve if you have not written in any markup language before. I will list each of the personal pro's and con's I see on each one, and preliminary sorry because I am a tad biased towards Markdown:

Wikia

Pros

• Much easier to write and is generally beginner-friendly - MediaWiki has gained its popularity and use for many many sites like Wikipedia, Wikia, and many others, because it is generally easy to use for all ages and skill levels.
• More popular - Wikia is extremely popular along with Curse/GamePedia and self-made wikis. That also means that wikis made with it are prioritized more in search engines.
• Has tools and extensions built-in - Wikia has a collection of useful extensions to improve your Wiki. It also maintains various statistics and counts for your Wiki.
• Many resources - Part of what makes it easy to learn MediaWiki syntax and writing your wiki in general is the great number of resources available on the internet, since most people use the site anyways.

Cons

• EXTREMELY clunky and riddled with ads - In my personal experience using Wikia on computers, laptops, tablets, phones, it has always been clunky and laggy. Part of the reason why is because they are riddled with MANY ads. I have adblock turned on in my browser, and happy are you if you do too, it shows it's blocking 24 ads. It gets worse on mobile when you use a browser, but I might be wrong about the mobile experience since they have an app that I have not tried out.
• Not visually appealing - Have fun trying to edit on the web; you barely have shortcuts and the web editor is also clunky and ugly, plus you cannot easily use a much better local editor. The site overall also looks like garbage; you have a limited space, there is a top bar that you don't really need, it wastes precious space with "popular pages" and ads of other wikias/communities. Remember the time that wikis were independent and Wikia did not have a partial monopoly of wikis?

Markdown/MkDocs/GitLab

Pros

• Simple and clean - You can go visit the site right now and you will immediately see great simplicity in its design, mostly because of ReadTheDocs, the same theme Discord API Docs uses. There is a sidebar that straight up shows you a heirarchy of all the contents of the Wiki, and a search bar for convenience. The rest of the page is the content. Simple, clean, and straightforward.
• Works everywhere - The ReadTheDocs theme fits all devices, and is easy to use for all of them. It holds the same principles as the base desktop design, too.
• Fast - Since there are no ads, and a relatively small amount of images, if any, the site loads fast since you are only downloading text, a few images, and scripts. This contributes to the mobile usability; you can use it even if you have a slow internet connection, and get to the info you need quickly.
• Highly customizable and open source - Power users and people versed in web development will be able to change around just about every aspect using HTML and CSS. (looking for such people to help by the ways!) That is because all components of the site, including MkDocs and ReadTheDocs are open source.

Cons

• Steep learning curve - In order to start editing the actual documentation, one must have experience with Markdown and a knowledge of the essentials of HTML. Also, having basic knowledge of Git is recommended. Using Git makes things easier because that's literally the backbone of the site. You might quickly get the hang of Markdown and basic HTML, but Git is a little harder to get used to if one is coming from MediaWiki or is just beginning to edit wikis. (an exception are the people that already use Git for adding translations, who already have a basic knowledge of Git usage)

• Not super portable - Best practice in editing the wiki is cloning the files and editing them on a local editor, then committing and pushing them back to GitLab. Even though GitLab has its own IDE thingy, editing on mobile is opposed to desktop is not the easiest thing to do.

• Is relatively unpopular - Therefore, it is less prioritized by search engines. It might take a while to get the GitLab wiki to the top search results of "Mindustry Wiki", much less since the 3.5 wiki exists.

• Smaller collection of plugins and tools - MkDocs has a considerably smaller number of extensions written for it than Wikia, meaning that some functionality Wikia has may not manifest in MkDocs. One big one for me are the info card things; those look sick but it might take a while to implement them.

Which wiki sites support easy autogeneration of pages?

Specifically how and what? It might be easy to implement it into mkDocs or just make a script that makes markdown files from information. AFAIK, mkDocs does not natively support it, nor does Wikia.

Can ads/paid wikis be avoided?

Yes, completely, using GitLab Pages, where the WIP beta wiki is currently being worked on.

Can we get away with a wiki on GitHub?

I would strongly recommend against it. GitHub wikis are primarily used for extra info and documentation, but even so, people still use markdown files, their own README, or GitHub/GitLab pages and an easy documentation system for their documentations. Limited space, and slower because there are more unecessary components.

Thank you again Anuke for posting a question like this; the wikis really need to be worked on and I think this will gather the sort of attention and ignite discussion that pushes it forward, especially considering random members of the discord participate on useless discussions and s-post issues ;P

P.S. why aren't my drones helping me? :( using b72 fixed as of c0e425cf4631c29b295830232e1470cb811d64af

[Anuken]

Alright, we'll go with the GitLab wiki for now and consider other choices if issues arise.

I still think it's a bit early to start writing the wiki pages themselves (as content will still change before release), but it's worthwhile to start coding the system for creating and managing the pages. Unlike some other games (e.g. Minecraft), Mindustry already has a sort of wiki for its content in-game. It would be a waste not to use this information to automatically generate pages each release.

---

How I envision it would work

• Every release, a webhook would trigger and a headless version of the game would be launched.
• All content objects would be created and initialized.
• A separate wiki generator module module would go through all the content classes, categorizing them by type and assigning output folders per type.
• Each content object would have a page generated for itself, mirroring what is displayed in-game.
  • This would be done by simply fetching the stats per each type of content.
  • If UI code becomes a problem, it would not be particularly difficult to create a proxy Table object and scrape label/image information from there.
  • Icons of the needed size would be taken from the spritesheet and put into a separate folder.
  • Optionally, internal information about the content can be added to the page, such as the internal name and a source file link.
  • Links to related content can also be inserted (e.g. "which zones this ore appears in")

Potential issues with this system

Ideally, I would like each content information page to consist of an autogenerated page that is updated each release, along with a user-created section which lists additional information such as strategies, additional info, trivia, etc.

A simple way to do this would be to have an HTML comment in the middle separating the autogenerated section, with everything above it being automatically replaced every release. Would this be too confusing/obstructive for wiki editors? I'm not sure.

[skybldev]

I agree with the auto-generation system, although I, sonni and tceo would have to put much further thought into that. It's not too hard to create a simple js script that just modifies parts based on a regex or something but neither is it a trivial subject.

Currently, I see that as a big help since I have to manually re-sprite stuff and edit a lot of tables and things manually. If there are specific parts that are dynamic, that would be amazing:

• Value and sprite cells in tables
• Item and object descriptions
• Automatically downloading sprites like you said
• Possibly updating the roadmap along the way too?

A simple way to do this would be to have an HTML comment in the middle separating the autogenerated section, with everything above it being automatically replaced every release.

HTML comments that act as delimiters imo will be effective. I might be able to get a proof-of-concept up by like tomorrow using fs.

Would this be too confusing/obstructive for wiki editors?

I don't think that would be too obtrusive. You've asked at the right time when areas that are too human aren't a large part of the wiki yet.

This would be done by simply fetching the stats per each type of content

Could you possibly get all you need from just the item definitions (e.g. files like core\src\io\anuke\mindustry\content\Items.java)?

Optionally, internal information about the content can be added to the page, such as the internal name and a source file link

IMO that is necessary. Seeing that this wiki is called a "documentation" there should be some sort of overlap between the two functions. This would be especially useful for people that would like to contribute to the game.

P.S. have you seen Jibbyy anywhere on the discord since I left?

[Anuken]

Possibly updating the roadmap along the way too?

Do we need a roadmap on the wiki? I think a link to the Trello should be enough.

Could you possibly get all you need from just the item definitions (e.g. files like core\src\io\anuke\mindustry\content\Items.java)?

For very simple content like items, technically yes, but I would highly recommend against it. For blocks, however, it's out of the question. Many types of blocks have dynamic stat definitions based on multiple levels of inheritance, and attempting to extract that kind of information automatically would be... unwise. Writing a page generation system in Java to integrate with the game would be the best option in this scenario.

have you seen Jibbyy anywhere on the discord since I left?

They appear to have sent a few messages since then, yes. Why?

[skybldev]

Do we need a roadmap on the wiki? I think a link to the Trello should be enough.

I mean this one: https://docs.google.com/spreadsheets/d/1wIRdj09dGPf28hX6y-YM_uP2Xp78T11raeDPbm21Ee8

For very simple content like items, technically yes, but I would highly recommend against it.

Ah, I see.

They appear to have sent a few messages since then, yes. Why?

I've assigned a branch to him which he abandoned and I would like to have him back for even a short time to finish it up so I can merge it with master.

[skybldev]

Finished my proof of concept, all without any external modules. https://www.youtube.com/watch?v=4jBeIgtmEeA

WARNING - FILTHY CODE: https://gist.github.com/Luxray5474/f8bcc7d8a4e1ddb0d36deb975a16d848

Also, as you can see, the delimiter isn't actually an HTML comment, but is an empty hyperlink. I've tested it on mkdocs, and it does not appear. Some really nice optimizations.

[Anuken]

That works, but what we'll need for the production version is a server that listens to specific events (e.g. release event webhooks) and:

• pulls the wiki repo
• launches a headless mindustry version
  • this creates the content description files
  • the same program splices them into the existing wiki content
• commits and pushes to the wiki repo using a login token/key

(yes, I know the last message was 2 weeks ago, I just decided to get back to this issue since 73 was just released)

[skybldev]

I was waiting lol. I see the efficiency in that, and since you know java much more than I do, you can actually go ahead and start on it now. I don't think conferring with tceo and sonni would help at all. 📄

The reason why I made a js proof of concept and made it take in web requests was because originally I thought of the script to just send a large file full of the stuff to the server with the js program, which then processes it, but that is inefficient obviously.

Also, as opposed to a standalone server, why don't you just use CI? Can't you just set it to trigger on a specific event?

edit: also I spent wayyyy too much time trying to figure out how to batch the entries into files over the week and I only finished it today which is conveniently the same day you post that message lol.

[Anuken]

Also, as opposed to a standalone server, why don't you just use CI? Can't you just set it to trigger on a specific event?

Good point. I suppose I could set up a system where the Mindustry CI clones the wiki repo, runs the script and pushes the files.

[skybldev]

Any other thoughts? Also, I agree with the idea of the program doing all the things instead of having two separated programs communicating over the internet. I think it would be more secure.

[Anuken]

I'll bring up any issues I find with the wiki system here. For now, I've created the generator repository which IntelliJ thinks is CoreBot for an unknown reason.

[skybldev]

Awesome. And now, I have a nice markdown updater i might publish later on, because of the usefullness of its concept :D

One thing, because of the nature of CI, virtual 'disk space' is cleared when a pipeline ends, and cloning the repo every single time is quite inefficient, especially in the future when it will be full of images and maybe other media. Maybe that's our only choice though.

[Anuken]

Unless it takes actual hours to clone and run, I don't think that will be an issue. As long as the wiki gets updated within a day of release, it's fine.

[Anuken]

How do translations work with the Gitlab wiki? I'm considering implementing the generation system using bundles of template text, similarly to how the main game functions. Is this worth the effort?

[skybldev]

Not yet. My plan is to begin the translation of the wiki once it has gained a considerable amount of contributors (and readers), even more so if they come in a wide range of ethnicities. One that's begun, we'll only be focusing on 5 major languages, or the 5 most used languages in the game's userbase (which will be easy because of the appalling amount of people we have in the discord which imo represent the (unseen) userbase as a whole more than well), maybe adding more if there are, well, more.

[Anuken]

Proof-of-concept works.

Time to figure out how to structure these pages and incorporate the sprites.

[skybldev]

Awesome :D

Would you like me to setup a test repo for the wiki, so you can dabble with it? Also it can update pages too right? (it's main function)

(also, what IDE are you using? it looks real slick)

[Anuken]

The generation system is more or less done now. There's still a lot of info missing, and only 3 types of content have generators, but the core of it is complete.

Would you like me to setup a test repo for the wiki, so you can dabble with it?

I think we should move on to creating the real repository for the wiki.

Also it can update pages too right? (it's main function)

Yes. It can splice new generated page content in before the old stuff.

[skybldev]

Wait so, we're making a new format for the all wiki pages?

I think we should move on to creating the real repository for the wiki.

Please clarify 😕 We already have a repo.

[Anuken]

Please clarify. We already have a repo.

I thought that was general documentation for modding, not the location for a new wiki. It seems a bit weird to have an official wiki at mindustrymodders.gitlab.io.

Wait so, we're making a new format for the all wiki pages?

I'm not entirely sure what you mean by 'new' format. While the wiki you posted previously has files for blocks, they're all merged into one page and missing a lot of details-- it's not the same thing at all.

[skybldev]

I thought that was general documentation for modding, not the location for a new wiki. It seems a bit weird to have an official wiki at mindustrymodders.gitlab.io.

Ohhh, well then, I'll move over some stuff to a new repo this weekend probably.

While the wiki you posted previously has files for blocks, they're all merged into one page and missing a lot of details-- it's not the same thing at all.

Obviously it is not done yet. If you look at the planner I am still working on getting items done (really slowly). Here is the hierarchy:

• content type (items/blocks/liquids/player/etc)
  • category (except for items) (like defense, distribution)
  • members (the individual block for example)

Each content type is a 'folder' in the sidebar. The category is one big file that starts with a table. The 'members' are subheadings of the file separated by

---

to make them their own 'portion'. Of course, each 'portion' would be treated as if it were a page, with all of the information about the item, etc. Why that instead of separate files? 1) It leverages one of the features of the sidebar in mkdocs, each subheading looks like its own article, and therefore can be treated as such, and 2) it makes a more streamlined and concise reading and writing experience. The other thing you are looking for is just a short scroll away, and you go through less folders when editing.

[Anuken]

Why that instead of separate files?

I'm not sure about this. We could have a (autogenerated) main block navigation page with links for every block separated by category, but individual blocks should stay separate. Each block may have a lot of information available about it; it would be cleaner to have a separate page to prevent clutter. This is what every other wiki I've seen does, and it seems to work well.

Another side-note is that putting all the blocks into one file makes splicing significantly more difficult.

[skybldev]

Sure, I guess. I'll try to divide it this weekend too.

[Anuken]

Wait, why divide it? Are you referring to the block pages?

[skybldev]

Yes, since they already each have like a couple paragraphs-full of information.

Also, please confirm to me the page format/layout you decide on when you do.

[Anuken]

full of information

These pages? I don't see what you mean. This is all information that will be automatically generated in the block pages; why keep it? I don't see any of the pages in the current blocks folder being useful. The same applies to items, liquids and status effects.

[skybldev]

please kindly checkout the other branches

https://gitlab.com/MindustryModders/mindustry-documentation/blob/items-rev1/docs/items.md

[Anuken]

From what I can tell, the only information we can use from those pages is the descriptions. Everything else is (or can be) generated.

The splicer expects files to be generated first, then descriptions and such to be added later. I don't think you should split anything up until the generated content is working on the main wiki.

[skybldev]

Ohhhh, now I get it. I'll setup a GitLab Pages repo (why not github? ask tceo.) rn and give you a token privately afterwards so you can begin generating the files.

[Anuken]

GitLab Pages

I've asked TCEO, and he hasn't responded yet. But, regardless, I don't think we should put in on Gitlab pages unless it has some feature that GitHub doesn't. For one thing, I don't have a GitLab account, and for another, it's simpler to keep everything on one site.

---

EDIT:

Not that it changes my stance on the subject.

[skybldev]

For starters, gitlab has its own CI and Runner system which integrates into gitlab pages, which means all deployment happens in one place.

It also has its own "Web IDE" which means users can make quick edits without using an editor.

Also I think part of why tceo doesn't like github because of its acquisition by microsoft, but that's just an assumption.

[Anuken]

For starters, gitlab has its own CI and Runner system which integrates into gitlab pages, which means all deployment happens in one place.

But weren't we planning on using the Mindustry CI (which is to say, Travis) anyway? I don't see how this changes things.

It also has its own "Web IDE" which means users can make quick edits without using an editor.

Github also has online editing, although I'm not sure how they compare.

[skybldev]

But weren't we planning on using the Mindustry CI (which is to say, Travis) anyway? I don't see how this changes things.

GitLab CI and Runners are what deploy the site in the first place. I don't know how GitHub Pages works, though, so I cannot really make a comparison.

Github also has online editing, although I'm not sure how they compare.

GitLab has a full-blown Monaco based editor with syntax highlighting, a nifty file explorer sidebar, and git functionality. Basically a mini VS Code.

https://i.imgur.com/IsKLHd1.png

Even though GitLab has its own IDE thingy, editing on mobile is opposed to desktop is not the easiest thing to do.

This might make mobile editing easier than doing so with GitHub.

[Anuken]

GitLab CI and Runners are what deploy the site in the first place. I don't know how GitHub Pages works, though, so I cannot really make a comparison.

From what I've used of GitHub Pages, they also have an automated deployment system. I haven't used it enough to see how it works either.

This might make mobile editing easier than doing so with GitHub.

The syntax highlighting isn't as good, but I'd say this has all the functionality that is needed.

[skybldev]

So, GitHub it is then? I have listed all the features I find useful as opposed to GitHub, but I would like to respect your opinion. I guess we could keep everything on one site.

[Anuken]

I don't think a marginally better web editor is worth moving to GitLab for. There's going to be a lot more people with GitHub accounts than GitLab, and as we're using this site for discussion and Mindustry in the first place, I believe it would be more convenient in the long run to stay here.

[skybldev]

Alright. I'll see if I can import it into GitHub.

Do you think we should setup an organization so we can put all repos (arc, mindustry, wiki, wikigen) under one 'name' and 'hub'?

please tell tceo too :^)

[Anuken]

I already have something resembling an organization here. Not sure about moving the main Mindustry repository there, though.

[skybldev]

Then, you decide. The reason I suggested putting it under a group is it seems a little weird to have a wiki with many (potential) contributors under one name. One thing is I wouldn't like to create it under my name.

[Anuken]

I could invite you to the organization, and you could create the wiki there. I don't think anything besides the wiki tools and site should be under the organization, though.

[skybldev]

Perfect. 👍

[skybldev]

@Anuken I am going to use Travis CI as a deployment tool according to this StackOverflow answer https://stackoverflow.com/questions/50892018/auto-build-an-mkdocs-documentation-in-travis-ci. It needs organizational access though.

[Anuken]

Which access level do you need?

[skybldev]

I have no idea, it just says:

Also I don't think I need anything higher than what I have now.

[Anuken]

I don't see anything about a request; no notifications and nothing showing up in the organization page. What does the info button say?

[skybldev]

[Anuken]

Found it in my email. Should be approved now.

[skybldev]

Thanks 👍

[Anuken]

I see the wiki builds now. Should I begin testing the page generation system on the wiki's directory structure, or are you planning on making more changes?

[skybldev]

I will make a branch for that soon.