Comfort HRM, The DX that can't be beat
Lorem ipsum...
diff --git a/404.html b/404.html new file mode 100644 index 0000000..4e863b2 --- /dev/null +++ b/404.html @@ -0,0 +1,21 @@ + + +
+ + +404
But if you don't change your direction, and if you keep looking, you may end up where you are heading.
Welcome to the about page.
This markdown supports html elements like the p
tag coupled with inline styles
Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s.
Even satire code snippets with syntax highlighting are also supported. 😅
const lang = prompt("What is your favorite programming language?");
+
+(lang === "JavaScript") | (lang === "javascript") | (lang === "js")
+ ? alert("JavaScript to the world! 🚀🟡")
+ : alert(\`We don't permit such languages here 💩\`);
Of course, images are not left out.
Welcome to the about page.
This markdown supports html elements like the p
tag coupled with inline styles
Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s.
Even satire code snippets with syntax highlighting are also supported. 😅
const lang = prompt("What is your favorite programming language?");
+
+(lang === "JavaScript") | (lang === "javascript") | (lang === "js")
+ ? alert("JavaScript to the world! 🚀🟡")
+ : alert(\`We don't permit such languages here 💩\`);
Of course, images are not left out.
=0)c=r.activeElement;else{var f=i.tabbableGroups[0],p=f&&f.firstTabbableNode;c=p||h("fallbackFocus")}if(!c)throw new Error("Your focus-trap needs to have at least one focusable element");return c},v=function(){if(i.containerGroups=i.containers.map(function(c){var f=br(c,a.tabbableOptions),p=wr(c,a.tabbableOptions),C=f.length>0?f[0]:void 0,I=f.length>0?f[f.length-1]:void 0,M=p.find(function(m){return le(m)}),z=p.slice().reverse().find(function(m){return le(m)}),P=!!f.find(function(m){return se(m)>0});return{container:c,tabbableNodes:f,focusableNodes:p,posTabIndexesFound:P,firstTabbableNode:C,lastTabbableNode:I,firstDomTabbableNode:M,lastDomTabbableNode:z,nextTabbableNode:function(x){var $=arguments.length>1&&arguments[1]!==void 0?arguments[1]:!0,K=f.indexOf(x);return K<0?$?p.slice(p.indexOf(x)+1).find(function(q){return le(q)}):p.slice(0,p.indexOf(x)).reverse().find(function(q){return le(q)}):f[K+($?1:-1)]}}}),i.tabbableGroups=i.containerGroups.filter(function(c){return c.tabbableNodes.length>0}),i.tabbableGroups.length<=0&&!h("fallbackFocus"))throw new Error("Your focus-trap must have at least one container with at least one tabbable node in it at all times");if(i.containerGroups.find(function(c){return c.posTabIndexesFound})&&i.containerGroups.length>1)throw new Error("At least one node with a positive tabindex was found in one of your focus-trap's multiple containers. Positive tabindexes are only supported in single-container focus-traps.")},y=function w(c){var f=c.activeElement;if(f)return f.shadowRoot&&f.shadowRoot.activeElement!==null?w(f.shadowRoot):f},b=function w(c){if(c!==!1&&c!==y(document)){if(!c||!c.focus){w(d());return}c.focus({preventScroll:!!a.preventScroll}),i.mostRecentlyFocusedNode=c,Ar(c)&&c.select()}},E=function(c){var f=h("setReturnFocus",c);return f||(f===!1?!1:c)},g=function(c){var f=c.target,p=c.event,C=c.isBackward,I=C===void 0?!1:C;f=f||Ae(p),v();var M=null;if(i.tabbableGroups.length>0){var z=l(f,p),P=z>=0?i.containerGroups[z]:void 0;if(z<0)I?M=i.tabbableGroups[i.tabbableGroups.length-1].lastTabbableNode:M=i.tabbableGroups[0].firstTabbableNode;else if(I){var m=ft(i.tabbableGroups,function(V){var U=V.firstTabbableNode;return f===U});if(m<0&&(P.container===f||Re(f,a.tabbableOptions)&&!le(f,a.tabbableOptions)&&!P.nextTabbableNode(f,!1))&&(m=z),m>=0){var x=m===0?i.tabbableGroups.length-1:m-1,$=i.tabbableGroups[x];M=se(f)>=0?$.lastTabbableNode:$.lastDomTabbableNode}else ge(p)||(M=P.nextTabbableNode(f,!1))}else{var K=ft(i.tabbableGroups,function(V){var U=V.lastTabbableNode;return f===U});if(K<0&&(P.container===f||Re(f,a.tabbableOptions)&&!le(f,a.tabbableOptions)&&!P.nextTabbableNode(f))&&(K=z),K>=0){var q=K===i.tabbableGroups.length-1?0:K+1,H=i.tabbableGroups[q];M=se(f)>=0?H.firstTabbableNode:H.firstDomTabbableNode}else ge(p)||(M=P.nextTabbableNode(f))}}else M=h("fallbackFocus");return M},S=function(c){var f=Ae(c);if(!(l(f,c)>=0)){if(ye(a.clickOutsideDeactivates,c)){s.deactivate({returnFocus:a.returnFocusOnDeactivate});return}ye(a.allowOutsideClick,c)||c.preventDefault()}},T=function(c){var f=Ae(c),p=l(f,c)>=0;if(p||f instanceof Document)p&&(i.mostRecentlyFocusedNode=f);else{c.stopImmediatePropagation();var C,I=!0;if(i.mostRecentlyFocusedNode)if(se(i.mostRecentlyFocusedNode)>0){var M=l(i.mostRecentlyFocusedNode),z=i.containerGroups[M].tabbableNodes;if(z.length>0){var P=z.findIndex(function(m){return m===i.mostRecentlyFocusedNode});P>=0&&(a.isKeyForward(i.recentNavEvent)?P+1 H)for(;C<=U;)Oe(u[C],b,S,!0),C++;else{const W=C,z=C,Q=new Map;for(C=z;C<=H;C++){const _e=d[C]=R?ze(d[C]):Re(d[C]);_e.key!=null&&Q.set(_e.key,C)}let te,ae=0;const Ae=H-z+1;let gt=!1,es=0;const Lt=new Array(Ae);for(C=0;C {const{el:S,type:O,transition:x,children:R,shapeFlag:C}=u;if(C&6){tt(u.component.subTree,d,m,v);return}if(C&128){u.suspense.move(d,m,v);return}if(C&64){O.move(u,d,m,pt);return}if(O===me){r(S,d,m);for(let U=0;U INFO Documentation is a crucial aspect of software development that is often neglected by developers due to the hassle of maintaining one, or even choosing the right tools to use. This is why it's important to use tools that simplify this process. In this tutorial, you'll learn how to build a complete docs site quickly by utilizing a modern tool called, VitePress. VitePress is a simple and performant static site generator built on top of Vite for creating docs in a matter of minutes. It is powered by Vuejs, and Vite with built in customizable components. VitePress powers some popular documentation sites like Vuejs, Vitest, faker.js, and Vite itself. To follow along with this tutorial, you need to have a basic understanding of the following: Here's a screenshot of what you'll be building at the end of this tutorial. If you already have a folder created, you can skip this step to the next one if not, use the following command to create a project folder and move into the folder. Next you need to initialize with your preferred package manager. I'll be using NPM for the rest of this guide. If you used the first command, you'll be prompted with certain questions, complete them as appropriate. After a successful operation, you should have a package.json file in your root directory; This is where the VitePress dev dependency will be installed. Next step is to add VitePress and Vue as dev dependencies to your project. You've successfully installed VitePress and Vue and added it as a dev dependency. Now you can start creating creating your respective doc files, but before you do that, I believe it's essential to explain how VitePress works. VitePress makes use of Markdown This folder behaves similar to the Now you understand how that works, you can now create your respective doc files. You can create the docs folder and the index.md file manually, or you can do it with the terminal like a hacker. This command is simply creating a folder called docs and adding an index.md file containing a h1 element that says, "Hello World". With this, you can boot up your dev environment to see what has been created so far. In other to run your docs locally, you need to add the following scripts inside the package.json file. Simply copy the code below and replace it with the "script" object. Finally, the documentation site can be served on a local server by running the command below: This will start a hot-reloading development server at All you had to do was add the markup and VitePress handled the looks from it's template engine. In the next session, you'll learn how you can customize the docs to fit your needs. First create a To test this config file, you can start by changing the meta title and description of your docs site. Copy this markup and paste into the If you check the dev tools, you should see the changes in the meta title and description. In other to change the logo title and add an image, copy the markup below and paste it into a new object called For the image source, you can pass in an image URL or specify the path to a local image. To do it locally, make sure you place the image within the WARNING Note: files in the public directory are served at the root path. So instead of Customizing the Essentially navigating to Navigation links can also be dropdown menus too. To add one, simply replace any of the links property with the items object which contains an array of links. Now changelog will become a dropdown menu with the respective links you pass inside. Navigation menus usually have social icons visitors can use to visit your social platforms. To add that, define a new object called socialLinks inside themeConfig and simply pass in the social icon and the link you want it to navigate to. By default only 7 popular icons are provided. If you want to add a custom icon, use the SVG property to define an svg image. WARNING For the SVG icon, make sure you add the role="img" property, this allows the string convert it properly. VitePress also comes with built-in components like sidebar menus. To add a sidebar, create an object called sidebar and inside we add nested objects that takes in three values; the nested title, collapsible functionality (Default is set to true) and the nested links. By adding collapsible: "true" to the sidebar object, it shows a toggle button to hide/show each section. You can create as much sections as you want. You can see section B is not collapsible and we have that aesthetic next page button on the bottom of the page. As explained earlier, VitePress automatically converts every Since you've created your nav links and pointed them to their respective URLs, you can access these pages easily by creating them. Create these files inside your docs folder and add a simple markup inside them just to see how this works. This page is basic markdown so all your markdown syntax like links, code blocks, headings, etc works here. Just for testing purposes, copy this markdown content and paste it inside any of the Great! You've set-up the docs, added a navigation menu with dropdown feature, added a sidebar, and customized the links to navigate to different pages. Next up, let's work on the home page. Just like every other components, VitePress provides us with markup for building the home page. I've broken it down into three parts: Hero, features, and footer section. First, we'll start with the hero section. Replace the Hello World text in the Additionally, you can also add a features section after the hero section. Simply paste the code below under the hero objects. You can add a footer message on the bottom of the page but this will only show up in the home page. WARNING The footer will not be displayed when the SideBar is visible. To add the footer component, go to the Aside from the markup, you can also customize the components using custom CSS to change things like fonts family, colors, layout, ETC. The default theme CSS is customized by overriding root level CSS variables. If you want, you can check out the full list of css variables customizable. To do get started, create a If you ran into any issues with the terminal command, just create the files manually and move on to the next step. Here's an overview of the folder structure. After creating these files, inside the The colors are controlled by the CSS variables. You can simply replace them with any colors you want. TIP This color has a provision for both light and dark mode. So make sure you change them accordingly. Here's an example of my custom colors If you don't see the effects immediately, try ending the server and starting it again. Aside from the color themes, you can also override other things like, font family, typography, layout, breakpoints, etc. Google fonts can be imported inside the CSS file to override the default font family. With the You've successfully customized the theme and changed the font family using CSS. Though there's more you can do in regards to styling, but at this point, I'm sure it's clearer how you can customize your docs with CSS. Let's discuss hosting in the next section. You can publish or host your docs site when you're done to different platforms like: Netlify, Vercel, AWS Amplify, etc. First, run the build command This should create a new dist folder that contains all the static files of your docs. In your hosting service, add these commands to their respective fields. Build command: npm run docs:build Output directory: docs/.vitepress/dist This should create a new After editing the settings, save, and deploy. In this tutorial, you've set-up a full-fledged documentation site and customized it using CSS and VitePress built-in components. However, this tutorial only covers a fragment of what is possible with VitePress, to learn more, check out the VitePress docs. If you are an open source ardent like myself or you enjoy hearing about such cool projects, do follow me on my socials so you don't miss my next post. Cheers. 🍷 Streamline your HR process. A free to use template for creating docs for your projectsHow to build modern docs with VitePress
Definition
Prerequisites
Step. 1: Create a new project
mkdir project-name
+cd project-name
npm init
+// or use this command if you want to skip all the questions
+npm init -y
Step. 2: Install VitePress
npm install vue vitepress --save-dev
+// or
+npm install -D vue vitepress
How does VitePress work?
.md
files for it's markup which is automatically converted into static HTML. In other for this to work, a special folder called docs
is created in the root directory.pages
folder in NextJS, where any .js
file created in the directory is automatically treated as a web page. In this case a file called index.md
will be the treated as index.html
and serve as the root of your docs template.Step 3. Create respective files
mkdir docs && echo '# Hello VitePress' > docs/index.md
Step 4: Boot up dev environment
// package.json
+"scripts": {
+ "docs:dev": "vitepress dev docs",
+ "docs:build": "vitepress build docs",
+ "docs:serve": "vitepress serve docs"
+ },
npm run docs:dev
http://localhost:5173
, and you can visit it to see your docs site.Output
How to customize your docs
.vitepress
folder inside the docs directory you created earlier on. This is where all VitePress-specific files will be placed. Inside this new directory, you need a config.js
file. Again, you can use the terminal command as a hacker.mkdir .vitepress && touch .vitepress/config.js
config.j
s file.// .vitepress/config.js
+export default {
+ title: "Comfort HRM",
+ description: "An awesome docs template built by me",
+};
Title and Logo
themeConfig
inside the same config.js
file. This will overwrite the current title and add a logo your docs site.// config.js
+export default {
+ themeConfig: {
+ logo: "/logo.png",
+ siteTitle: "Comfort HRM",
+ },
+};
public
directory.Output
../public/logo.png
, just use /logo.png
.Navbar
Navbar
is a pretty straightforward process as well. Inside your themeConfig
file, paste the markup below. Here we have an object that contains two properties. The anchor text text
, and the path, link
defines the URL path.// .vitepress/config.js
+{
+ // ...
+ nav: [
+ { text: "About", link: "/about" },
+ { text: "Contact", link: "/contact" },
+ { text: "Guide", link: "/guide" },
+ { text: "Configs", link: "/configs" },
+ { text: "Changelog", link: "https://github.com/Evavic44" },
+ ],
+ // ...
+}
http://localhost:5173/about
should take you to an about page(though we haven't created that yet).Output
// .vitepress/config.js
+{
+ text: "Changelog",
+ items: [
+ { text: "v0.0.1", link: "/item-1" },
+ { text: "v0.0.2", link: "/item-2" },
+ { text: "v0.0.3", link: "/item-3" },
+ ],
+},
Output
Social Icons
// .vitepress/config.js
+socialLinks: [
+ { icon: "github", link: "https://github.com/Evavic44/Comfort HRM" },
+ { icon: "twitter", link: "https://twitter.com/victorekea" },
+ { icon: "discord", link: "", target: "_blank" },
+];
}
+ "discord"
+ "facebook"
+ "github"
+ "instagram"
+ "linkedin"
+ "slack"
+ "twitter"
+ "youtube"
+ { svg: string };
+{
Sidebar
// .vitepress/config.js
+sidebar: [
+ {
+ text: "Section A",
+ collapsible: true,
+ items: [
+ { text: "Introduction", link: "/introduction" },
+ { text: "Getting Started", link: "/getting-started" },
+ ],
+ },
+ {
+ text: "Section B",
+ collapsible: false,
+ items: [
+ { text: "Introduction", link: "/introduction" },
+ { text: "Getting Started", link: "/getting-started" },
+ ],
+ },
+ {
+ text: "Section C",
+ collapsible: true,
+ items: [
+ { text: "Introduction", link: "/introduction" },
+ { text: "Getting Started", link: "/getting-started" },
+ ],
+ },
+ ],
Output
Page Routing
.md
file inside the root of the docs directory to static html that can be accessed in the address bar. For instance the index.md
is converted to index.html
, and about.md
, about.html and so on.docs/
+├── .vitepress/
+│ └── config.js
+├── public/
+│ └── logo.png
+├── about.md
+├── contact.md
+├── guide.md
+├── configs.md
+└── get-started.md
.md
file you just created.# About
+
+Welcome to the about page.
+
+This markdown supports html elements like the \`p\` tag coupled with inline styles
+
+<p style="color: #ff7340; border: 1px solid rgba(255, 135, 23, 0.25); border-radius:5px; padding: 1rem;">Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s.</p>
+
+Even satire code snippets with syntax highlighting are also supported. 😅
+
+const lang = prompt("What is your favorite programming language?");
+
+(lang === "JavaScript") | (lang === "javascript") | (lang === "js")
+? alert("JavaScript to the world! 🚀🟡")
+: alert(\`We don't permit such languages here 💩\`);
+
+Of course, images are not left out.
+
+<img src="/logo.png" alt="Comfort HRM logo">
Output
Customizing the home page.
Hero Section
index.md
page with the following markup.# docs/index.md
+---
+layout: home
+
+hero:
+ name: Comfort HRM
+ text: Streamline your HR process.
+ image:
+ src: /logo-big.svg
+ alt: Comfort HRM logo
+ tagline: A free to use template for creating docs for your projects
+ actions:
+ - theme: brand
+ text: Get Started
+ link: /get-started
+ - theme: alt
+ text: View on GitHub
+ link: https://github.com/evavic44/Comfort HRM-template
+---
Features Section
# /docs/index.md
+---
+link: https://github.com/evavic44/Comfort HRM-template
+
+features:
+ - icon: ⚡️
+ title: Comfort HRM, The DX that can't be beat
+ details: Lorem ipsum...
+ - icon: 🎉
+ title: Power of Vue meets Markdown
+ details: Lorem ipsum...
+ - icon: 🔥
+ title: Simple and minimal, always
+ details: Lorem ipsum...
+ - icon: 🎀
+ title: Stylish and cool
+ details: Lorem ipsum...
+---
Output
Footer
config.js file
and paste the markup inside the themeConfig
object// .vitepress/config.js
+ footer: {
+ message: "Released under the MIT License.",
+ copyright: "Copyright © 2022-present Comfort HRM",
+ },
Output
Custom CSS
.vitepress/theme directory
, and inside this theme folder, add an index.js
and custom.css
file. If you've been following along, you can use the terminal command below to do this quickly.mkdir docs/.vitepress/theme && touch docs/.vitepress/theme/index.js && touch docs/.vitepress/theme/custom.css
docs/
+├── .vitepress/
+│ ├── config.js
+│ └── theme/
+│ ├── index.js
+│ └── custom.css
+├── public/
+│ └── logo.png
+├── about.md
+├── contact.md
+├── guide.md
+├── configs.md
+└── get-started.md
.vitepress/theme/index.js file
, paste the import commands.// .vitepress/theme/index.js
+import DefaultTheme from "vitepress/theme";
+import "./custom.css";
+
+export default DefaultTheme;
Color Theme
/* .vitepress/theme/custom.css */
+
+:root {
+ --vp-c-brand: rgb(255, 115, 64);
+ --vp-c-brand-light: rgb(255, 87, 25);
+ --vp-c-brand-lighter: rgb(255, 115, 64);
+ --vp-c-brand-dark: #ff622d;
+ --vp-c-brand-darker: rgb(226, 60, 0);
+
+ --vp-c-sponsor: #fd1d7c;
+}
Fonts
@import url(https://fonts.googleapis.com/css?family=Space+Mono:regular,italic,700,700italic);
+@import url(https://fonts.googleapis.com/css?family=Space+Grotesk:regular,italic,700,700italic);
+
+:root {
+ --vp-c-brand: #ff7340;
+ --vp-c-brand-light: #ff5719;
+ --vp-c-brand-lighter: #ff7340;
+ --vp-c-brand-lighter: rgba(255, 135, 23, 0.25);
+ --vp-c-brand-dark: #ff622d;
+ --vp-c-brand-darker: #e23c00;
+
+ --vp-c-sponsor: #fd1d7c;
+
+ /* Typography */
+ --vp-font-family-base: "Space Grotesk", "Inter var experimental", "Inter var",
+ -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell,
+ "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif;
+
+ /* Code Snippet font */
+ --vp-font-family-mono: "Space Mono", Menlo, Monaco, Consolas, "Courier New",
+ monospace;
+}
--vp-font-family-base
variable you can change the main font and --vp-font-family-mono,
the font for code snippets.Output
Hosting
npm run docs:build
dist
folder that contains all the static files of your docs. In your hosting service, add these commands to their respective fields.npm run docs:build
docs/.vitepress/dist
Conclusion
Resources
Comfort HRM