docs: use vitepress

[marcalexiei]

Description

Use vitepressto build doc.

Motivation and Context

See associated issue: #3905

Usage examples

n/a

TODOs

• Convert all docs
  • Guides
  • Concepts
  • Reference
  • Improve homepage
• Update documentation unit tests
• Add copyright in the footer? not needed
• Be sure to run prettier on docs files when necessary
• Update CONTRIBUTING.md with new docs commands
• Automatic install via CI
• Replace module.exports in examples with ESM examples

Nav changes

Guides

• "Release" and "Upgrade commitlint" have been moved inside "Support"

• new "Getting started" page inside Guides (contains shared item for "Local setup" and "CI setup")

References

Rules page has been divided into two pages:

• Rules: contains the list of all rules
• Rules configuration: contains all the information about the rule (section on the top of the old rule page)

API

New section with a single page for each package (format, lint, load and read)

Support

a new collapsible section named "Support" which contains section.
In the future will include more content like troubleshooting information (#3894)

"Attributions"

new section with previous "Attributions" from docs/README.md content

Page preview (WIP)

Home

Guides: Local setup

References: Rules

[JounQin]

I would recommend to use https://rspress.dev/

[marcalexiei]

Pending discussion on #3905 (comment)

[marcalexiei]

I finished the main implementation of the docs using vitepress.
I will keep updating this PR description with the relevant changes I made.

Tip

If anyone want to take a look you can checkout this branch and try it locally and let me know what you think!
To run the server simply use yarn docs-dev.

@escapedcat, @JounQin if you have time I would like to hear any feedback!

---

@escapedcat, I have a question about automatic installation:

When opening "Actions" pages I see that a "pages build and deployment" workflow exists:
https://github.com/conventional-changelog/commitlint/actions/workflows/pages/pages-build-deployment

However Inside .github/workflows I haven't find any workflow file for it.

Probably there is some kind of magic that I'm missing here 😅.
There is any way I can see that code that runs this workflow so I can update it to use vitepress?

Just for reference this is the official vitepress deploy doc:
https://vitepress.dev/guide/deploy#github-pages

[escapedcat]

That's all "Github pages magic":

Currently everything in docs gets deployed.
We can adjust this if necessary.

[marcalexiei]

Thanks for the info.
When the new doc is completed we have to set "Build and deployment → Source" to "GitHub Actions":

The new doc requires a build step before is ready for deploy.

Anyway there is more job to do before this 😀

---

One last question: do you want to add a copyright in the footer?
In the current site there is none, however, since adding it is trivial let me know if you want it.

[escapedcat]

One last question: do you want to add a copyright in the footer?

No need, I think we're good without, right?

[marcalexiei]

I completed the doc update. PR description is updated with all relevant changes.

I added also the docs-deploy workflow to automatically deploy the docs on every push on master branch.

Let me know if other changes are needed 😉.

---

After merge GitHub Pages repo settings should be updated as described in my previous comment.

I never deployed pages on a custom domain so I'm not sure if other things should be update in the workflow / repository settings 😅.

[marcalexiei]

I have applied all requested changes. Let me know if other changes are needed.

[marcalexiei]

Thanks for your review @JounQin!

[marcalexiei]

@escapedcat, if you don't have changes that needs to be applied, new documentation is ready for merge.

[marcalexiei]

I just noticed that were many link pointing to the documentation with a conventional-changelog.github.io/commitlint domain.

I update all of them pointing to new the docs pages paths and to use commitlint.js.org domain.
I also removed some doc from single packages README.md and added reference to the docs pages and the associated md file used to generate it.

[escapedcat]

Thanks for pulling this off @marcalexiei .
We can adjust missing links later on if we missed some.
@JounQin thanks for your feedback and review!

Will try to merge and deploy this soon.

[escapedcat]

Merged. Exciting. Let's hope for the best 🤞

[escapedcat]

Had to update the branch-name, we're still on master :P
Looks great:
https://commitlint.js.org/

Thanks everyone! You keep this alive!

[escapedcat]

@JounQin would create a new major release tomorrow if you're good with that.
I would expect some incoming issues/feedback :P

[JounQin]

I would be glad for fixing any issues. 😁