docs: rewritting wiki with vitepress

[harilvfs]

yeah it’s kinda a big one jump for wiki or docs, we can say anything.

basically i have rewritten the whole wiki with vitepress docs build site.

and guess what, it looks fine. you can always look at the preview here

i don't know how you will merge this or accept this or not. but i am sure this may help users to view docs and read without any problem. it may be an easy way.

it may also be the easy way to contribute to docs, as you have wiki on github wiki pages where i don't know that we barely can contribute there.

so kind of my little time for this work. hope you like it. thank you.

btw if you merge this then you will need the following things to make this work:

first install bun from bun official site

if bun doesn't appear in your terminal, you may need to source the bun in ~/.bashrc or ~/.zshrc

then

bun install

i am assuming that you are in dotfiles repo dir

then initialize

bun add -D vitepress

now you are ready to go

you can run

bun run docs:dev

for viewing real-time changes

bun run docs:build

for building

and

bun run docs:preview

for previewing the built docs

also if you merge this for deploy, i have put a ci, but you also need to go to settings > pages > and in build and deployment, make the source from github actions. btw this step you should do before merging.

you can check out the actions part after that. after merging, click on the ci deploy, then after building, you will get something like https://mylinuxforwork.github.io/dotfiles/ you can put this in readme for docs site link.

btw if you are merging this pr, then squash and merge should be effective so it will crush all the commits into one commit that will be clean enough.

thanks again

[mylinuxforwork]

Wow. This looks beautiful. Thank you so much. Will look into it and come back to you later.

[mylinuxforwork]

Sorry. Had no time to test it. But I am super interested in it. Plrase give meca bit more time.

[harilvfs]

@mylinuxforwork yeah sure, i hadn't noticed you were working on the dotfile installer, so you're not getting enough time here to review prs.

btw, i have only 1 week of time at home after that, i think i'll be out of my country for some personal reason. so it would be better if we test and implement it soon, if possible :)

[mylinuxforwork]

@mylinuxforwork yeah sure, i hadn't noticed you were working on the dotfile installer, so you're not getting enough time here to review prs.

btw, i have only 1 week of time at home after that, i think i'll be out of my country for some personal reason. so it would be better if we test and implement it soon, if possible :)

is it possible to clone your dotfiles and install it in a separate github.io repo? I would like to doublicate the layout for all my projects.

[harilvfs]

@mylinuxforwork do you mean creating a separate repo and doing the wiki part there, or am I getting it wrong?

[mylinuxforwork]

@mylinuxforwork do you mean creating a separate repo and doing the wiki part there, or am I getting it wrong?

Exactly. I can imaging a setup where the homepage is an overview to available wikis and every project gets an own wiki in a subfolder like hyprland-dotfiles/..., hyprland-starter/..., hyprland-settings/... etc. And every subwiki is based on the same templates.

Is this possible to setup with vitepress?

[harilvfs]

@mylinuxforwork hmm. kind of need to see what we can do and how. currently i am not on my machine, i will see tonight and give you feedback.

i need to sit and work around what is the possible way to do that.

[mylinuxforwork]

Maybe a setup like this per application is better and the recommended way based on GitHub. Subfolder docs with vitepress in it. https://github.com/Aylur/astal/tree/main.

why do I need to build from action and not from branch?

[harilvfs]

this is not a static html site, this is kind of yeah basically a node-based site and we need to build it. github normal page and development doesn’t do that. for that, we need a ci workflow that can build the production site and deploy it to github pages.

and one thing, could you tell me what should we do? like is the current one i’ve done fine or does it need some changes?

like here you say:

@mylinuxforwork do you mean creating a separate repo and doing the wiki part there, or am I getting it wrong?

Exactly. I can imaging a setup where the homepage is an overview to available wikis and every project gets an own wiki in a subfolder like hyprland-dotfiles/..., hyprland-starter/..., hyprland-settings/... etc. And every subwiki is based on the same templates.

Is this possible to setup with vitepress?

and you can review the changes i have put a ci workflow there.

btw, sorry for my delayed response this happened because of our timezone diff.

if you want to test it yourself, you can clone my fork: https://github.com/harilvfs/dotfiles. check the first part of the description for a use case guide.

make sure to select GitHub Actions in the repo settings. you’ll find the CI workflow at ./github/workflows/docs.yml in my fork you can just look at it, no need to change anything.

you can fork my repo too that might be the easiest way to test the deployment.

after deployment, you’ll get the GitHub Pages URL like this:

[mylinuxforwork]

This is so great. I will test on my machine. Thank you so much for your contribution. Will mention your github profile in the credentials section.

[mylinuxforwork]

Will introduce the new documentation with the Dotfiles 2.9

[harilvfs]

@mylinuxforwork do you mean creating a separate repo and doing the wiki part there, or am I getting it wrong?

Exactly. I can imaging a setup where the homepage is an overview to available wikis and every project gets an own wiki in a subfolder like hyprland-dotfiles/..., hyprland-starter/..., hyprland-settings/... etc. And every subwiki is based on the same templates.

Is this possible to setup with vitepress?

most of the things in this we have covered in the docs. rather than getting a separate wiki for each, we can add them in the sidebar of the docs. like currently, we have a full guide of ml4w hyprland dotfiles wiki rewritten basically the same as wiki, i have just changed the things that were needed.

so in the future, if you want to add a dotfiles installer guide or hyprland stater (basically hyprland stater is kinda not needed but you may add it), we can just make a folder inside the docs dir and write markdown, then define it in .vitepress/config.ts. you can see how i have done it, you can easily do that. you don’t have to write typescript yourself and learn it (no, you don’t have to do that). i have done pretty much everything, you can just add a topic in the sidebar and put the path to the markdown in .vitepress/config.ts it’s that easy. basically you can have an overview and you will understand.

and btw if you want to add some new picture, video, or yt video in showcase you can do it in showcases/showcases.ts you can see there too how i have added

anywise, if you have a problem there, you can personally mail me too [email protected] ;)

[harilvfs]

@mylinuxforwork did the dotfile installer wiki get done from your side? if it is done, i will include it in this wiki

[mylinuxforwork]

Not needed. I will include it when it’s done. I am already testing the setup. Will clone your fork very soon. Maybe already today.

[harilvfs]

one suggestion for you, i see you do like merge pr directly on the repo (yeah that's fine). but it puts the user's all commits too into your repo. it's fine but for more understandable and clean way is doing squash and merge. i think i have mentioned this somewhere (i guess).

this is all upon you but i think it is the best way to merge pr onto the repo as if you see other people's also. basically squash and merge do that is crunch all the commit and make one commit so it can be easy to view later too what actual changes was, rather than static merge that puts all the commits of the user if user have done a lot of commit. for e.g you can see this https://github.com/harilvfs/carch/commit/ec503269b31db1f65e29e40e9bc31c8ea849c7e4. so it's more reliable. hope you get it.

btw the squash and merge you can do by pressing the arrow on the side of merge as shown in the image

[mylinuxforwork]

Thanks again for all your help. I am still learning the perfect github setup.

[harilvfs]

and btw this guide also helps you with forking and workflow things (when you have tested with this wiki https://github.com/leaningtech/webvm?tab=readme-ov-file#fork-deploy-customize btw this is not in any way linked with this wiki things, just for reference) ;)

[mylinuxforwork]

@harilvfs I have just cloned your docs folder and have integrated it into my repo. Will make some text changes and publish the new docs hopefully on the weekend. I will contact you in case of questions, if it's OK for you.

[mylinuxforwork]

Again.... Thank you so much for your support @harilvfs Just released the new documentation here: https://mylinuxforwork.github.io/dotfiles/

I will add a credential section and add your GitHub Profile. I will also post a message to the YouTube channel and will add a link to your profile as well. I hope that's OK for you?

[harilvfs]

@mylinuxforwork thank you so much for your kind words ;)

btw i assumed you would merge this pr as-is, but you mistakenly forgot to add node_modules, .vitepress/cache, and dist to the .gitignore

do this

git rm -r --cached node_modules
git rm -r --cached docs/.vitepress/cache
git rm -r --cached docs/.vitepress/dist

after that add the following in .gitignore

__pycache__/
bookmarks
.idea

# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
lerna-debug.log*
vscode

# Diagnostic reports (https://nodejs.org/api/report.html)
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json

# Runtime data
pids
*.pid
*.seed
*.pid.lock

# Directory for instrumented libs generated by jscoverage/JSCover
lib-cov

# Coverage directory used by tools like istanbul
coverage
*.lcov

# nyc test coverage
.nyc_output

# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
.grunt

# Bower dependency directory (https://bower.io/)
bower_components

# node-waf configuration
.lock-wscript

# Compiled binary addons (https://nodejs.org/api/addons.html)
build/Release

# Dependency directories
/node_modules
jspm_packages/

# TypeScript v1 declaration files
typings/

# TypeScript cache
*.tsbuildinfo

# Optional npm cache directory
.npm

# Optional eslint cache
.eslintcache

# Microbundle cache
.rpt2_cache/
.rts2_cache_cjs/
.rts2_cache_es/
.rts2_cache_umd/

# Optional REPL history
.node_repl_history

# Output of 'npm pack'
*.tgz

# Yarn Integrity file
.yarn-integrity

# dotenv environment variables file
.env
.env.test

# parcel-bundler cache (https://parceljs.org/)
.cache

# Next.js build output
.next

# Nuxt.js build / generate output
.nuxt
dist

# Gatsby files
.cache/
# Comment in the public line in if your project uses Gatsby and *not* Next.js
# https://nextjs.org/blog/next-9-1#public-directory-support
# public

# vuepress build output
.vuepress/dist

# Serverless directories
.serverless/

# FuseBox cache
.fusebox/

# DynamoDB Local files
.dynamodb/

# TernJS port file
.tern-port

# cache
docs/.vitepress/cache

# devicon
docs/.vitepress/devicon

then

git push --force

also, i saw you commented out // import "devicon/devicon.min.css" in index.ts ( you're not supposed to do that ). it's needed to show the distro icons for arch and fedora. see here:
https://harilvfs.github.io/dotfiles/getting-started/install#distro-based

sorry, but merging this pr should be totally fine i've already done everything properly.

btw just make those small changes and it should be good again ;)

btw, one reminder for you:

node_modules, dist, and cache have already been pushed to the repo, which increases the repo size. even after removing them with git rm -r --cached, the data is still stored in .git history.

yeah, i also made this mistake in my early days it's fine, no need to worry much. just follow the steps i mentioned above first :)

[mylinuxforwork]

@harilvfs Done. You're absolutely right. .gitignore updated and pushed.

[harilvfs]

@mylinuxforwork ok, now it's fine. did you read the last line i edited?

[mylinuxforwork]

Yes. I will check. The line had generated an error message during my first try.

[harilvfs]

there shouldn't be any issue or error using this. could you recheck?

#998