setup website with docusaurus v2
marcoieni opened this issue · 12 comments
Create the VSpaceCode website
This repository should contain the website of VSpaceCode built with https://v2.docusaurus.io/.
deploy
Ideally, master branch should contain files used by docusaurus to build the website. The generated files should be published to the gh-pages branch.
Deploy should be automatically done, ideally with github actions.
website content
Just to start, you can take the difference sections of the VSpaceCode README and which-key and put them in different sections of the documentation.
If you want, you can try to remove overlaps between the two READMEs.
keep it simple
You can start with a really simple template to begin with. No fancy stuff is needed.
If you disagree with some of the points above or you need help just leave a comment here :)
I initialized the website
I just looked at it for a little bit. We probably don't need a custom ssh key for this, it's bit weird to me that it needs that (I guess they are trying to reuse the command deploy). See facebook/docusaurus#2846
We can probably do something like https://github.com/VSpaceCode/VSpaceCode/blob/master/.github/workflows/keybindings.yml
The command sequence is probably like
npm install
npm run build
mv build deploy
I can take a stab at it tomorrow.
ok, but they recommend using yarn instead of npm (I don't know the difference). See the README.
yarn is an alternative package manager to npm. Since we are using npm in the other two repos, we probably should use npm (I also see that's what you use to set up the project). Functionally, they are pretty close these days AFAIK.
We can just update the README with npm instruction :) I can also fix that tomorrow
Updated both the github action and README :)
I feel like the website is in an acceptable state right now. Of course the docs need some improvements, but I get rid of all the placeholders and I have written the first blog post.
That's awesome. I thought we didn't need the blog feature, but it looks cool too. Thank you for writing the first blog post 👍 and all the work to make the website. It's looking good. Finally, we can do continuous improvements to the doc without the the change to readme those repos.
We can merge the changes in the develop to master and remove the develop branch on both repos. Either one of us can do that :)
I thought we didn't need the blog feature, but it looks cool too
yeah, me too, but it might be nice to share some thoughts from time to time :)
Finally, we can do continuous improvements to the doc without the the change to readme those repos.
Yes, removing the develop branch is good for new contributors. Anyway, now the problem just moved, since the website cannot contain docs about features that are not yet released.
Should we introduce a develop branch for the website repo (this one)? Maybe we could deploy it to develop.vspacecode.github.io if it is possible, which is what spacemacs does: https://develop.spacemacs.org/
Yes, removing the develop branch is good for new contributors. Anyway, now the problem just moved, since the website cannot contain docs about features that are not yet released.
haha...right😅
Should we introduce a develop branch for the website repo (this one)? Maybe we could deploy it to develop.vspacecode.github.io if it is possible, which is what spacemacs does: https://develop.spacemacs.org/
I am cool with that if we can do that. If not, we can also do versioning with docusaurus https://v2.docusaurus.io/docs/versioning
I just realized that the simpler solution is to setup the same workflow of the other repos.
I.e. we trigger the deploy action only on tags, not at every commit.
We can change this in the future, when we will need this behavior. Right now we might want to update the website more frequently, so it's ok like this.
I just realized that the simpler solution is to setup the same workflow of the other repos.
I.e. we trigger the deploy action only on tags, not at every commit.
That might still be problematic because two repos maintain two versions. But some sort of develop/master or release/next separation would still be nice.
We can change this in the future, when we will need this behavior. Right now we might want to update the website more frequently, so it's ok like this.
What we have right now may be fine for now, since I think there are still a lot of improvement can be made. Since the docs are hosted for both extensions with different version, something like the current/next like versioning with docusaurus might work. But it's still early for us I feel like.