Open pktiuk opened 3 years ago
vuepress would be good too, I've seen it being used around.
also maybe some code documentation could benefit developers(like collections of notes about where stuff is and how they tick)
Anything we choose, I think I'm ready to do the work for it...
vuepress would be good too, I've seen it being used around.
Do articles in vuepress use markdown?
also maybe some code documentation could benefit developers(like collections of notes about where stuff is and how they tick)
We need this, but I think in case of documenting code the best option would be documentation in code, because it could later be used to generate sites using doxygen and properly written comments integrate well with IDE.
@AriaMoradi
Firstly you should decide which tool you want to use.
It is good to check how it integrates with Github Actions (ready configs for building and hosting), what are theming options, and how easy is creating content for someone not familiar with creating web pages (Markdown-based generation is must-have).
As a simple example you can check my repo used to host my notes from some languages.
I would recommend also checking material theme for mkdocs: https://squidfunk.github.io/mkdocs-material/
It adds tons of features like multiple language support, buttons, code snippets, multiple configuration options for sites etc.
But also feel free to choose vuepress if you find it better fitting our needs.
@gombosg
Do you have any other suggestions/comments/ideas?
Do articles in vuepress use markdown?
It does. content is written in markdown and you can write additional vue to do custom styling.
And it does have some github actions
I think I'm going with vuepress, also the vue extensibility part is kinda exciting.
Do I need additional permissions to be able to manage this repo directly?
If so feel free to choose.
Also remember that some parts of wiki from legacy repositories can also come in handy (mentioned in the issue description).
You can easily clone them using git.
Do I need additional permissions to be able to manage this repo directly?
According to repo settings you should have already everything you need.
I'm not too opinionated. SSR (static site generators) is a fine approach.
They give a lot of flexibility if needed later but let us do a very basic site (no interactivity just plain ol' markup/down with some default theme.) at first, which may not be any harder to do than using mkdocs
.
I'd say, let's just start with mkdocs
but if this is also easy to set up and maintain, and in the end we just need to edit some .md
files, then why not.
I used Vue extensively and love its philosophy and just the right amount of opinionatedness it has. I guess Vuepress would be fine and it also has themes. Which is more important in our case than Vue, since we won't need much client-side interactivity for a docs site. :slightly_smiling_face:
@AriaMoradi I'd really appreciate if you could set up a basic repo with just a getting started hello world default, with some theme you like. I (we! @pktiuk vue is not hard! :laughing: ) can easily review and test it.
Then we could start brainstorming on content and creating it.
Yep the theming and extensibility is great(no custom element/page/menu/navbar in mkdocs
). in the end of the day, It's the content that's important.
@AriaMoradi I'd really appreciate if you could set up a basic repo with just a getting started hello world default, with some theme you like.
It's already there. Only the github actions auto-deploy part is not done.
The only interesting thing about it is index.html
s are generated from README.md
s. the rest is just put the markdown file, it will convert fine.
You can see the built site under where it should be: http://antimicrox.github.io
Awesome! I was living under a rock. I should turn on watching for that repo.
This repo.... Awesome work! I'll take a deeper look tomorrow, but IMO we could do some brainstorming here about table of contents then create child issues and close rhis.
You can see the built site under where it should be: http://antimicrox.github.io
I really like appearance of this website.
I have created milestone for these issues: https://github.com/AntiMicroX/antimicrox.github.io/milestone/1
Please link new issues with it.
@clickonrefresh
I assigned this task to you for clarity.
You can post here further comments about this task here.
When you will be familiarized with content of this repo tell us what do you think about this what have you found and what do you think needs to be done.
In case if you would find other tool than Vuepress
better for this task (or you think we did something wrong) let us know :D
Hi. I think vuepress works as it allows non technical people to just write markdown. There are so many tools available we could get lost in trying to choose the "right one" so I think sticking with vuepress is fine as it meets our requirements.
As for content, what would you like to see on the "main features" list? Some ideas:
These are just ideas to get it started and by no means intended as the final result.
This can be also used for generating SDL2 gamepad mappings like gamepadtool
Simple list of features is in readme https://github.com/AntiMicroX/antimicrox/#description
I think it is enough for now.
Main website can be simple, but it should be visually appealing
You could also add something about auto profiles.
Changing sets depending on currently active program. (it seems to be a rather nice and not very popular feature among other apps)
@clickonrefresh
Any progress?
@pktiuk should the 'auto profiles' feature be included on the landing page?
Yes, it is a nice feature.
@clickonrefresh
Could you provide any ETA for this task?
I think it would be good to discuss, how this site should be done both in terms of technical and in terms of content.
Technical side:
I think it would be the best solution to make this site using some kind of generator.
In my opinion the best would be combination of MkDocs with material-theme it would be deployed using GitHub actions after every push to master branch.
I think MkDocs would be suitable for us because:
(but this seems to be done mainly for documentation, not regular sites, I am not sure)
Content
I think this side should contain:
I am open for any comments and opinions about solutions proposed above.
Upvote & Fund