آموزش صفر تا صد ساخت یک سیستم مستندات با Vue و VuePress

مستندات یکی از نیازهای اساسی توسعه دهنده گان است و گاهی اوقات تهیه یک سیستم مستندات خوب برای پروژه ها کار دشواری است. در این پست می خواهیم با استفاده از سایت ساز استاتیک Vue یعنی VuePress یک سیستم مستندات تک صفحه ای ایجاد کنیم.

سرفصل های این آموزش

1. سایت‌های استاتیک چه چیزی هستند؟
2. چرا VuePress؟
3. پیش نیازها
4. نصب
5. ساخت فایل ها و فولدرها
6. تغییر استایل
7. انتشار پروژه در Netlify
8. نتیجه گیری

1- سایت های استاتیک چه چیزی هستند؟

سایت های استاتیک سایت هایی هستند که در همان جایی که ذخیره شده اند، مورد استفاده قرار می گیرند.

در سایت های استاتیک هیچ تعامل مستقیمی بین کلاینت و سرور برقرار نیست، مگر از طریق برنامه های شخص ثالث که در آن سایت مورد استفاده قرار می گیرد.

سایت سازهای استاتیک زیادی در اینترنت وجود دارند که هر کدام قابلیت های مختلفی را نسبت به دیگری دارد، بعضی از آنها سرعت و زمان بارگذاری بالای یک صفحه را به انعطاف پذیری بالا ترجیح می دهند، اما بعضی دیگر قابلیت های پیشرفته ای دارند.

سایت های استاتیک به دلیل سرعت بالای بارگذاری صفحات آن، ترجیح داده می شوند و در صورت نبودن یک سرور احتمال بروز مشکلات امنیتی در آن کاهش می یابد.

یکی از سایت سازهایی که اخیراً منتشر شده VuePress است. VuePress یک سایت ساز استاتیک است که به همراه یک تم پیش فرض عرضه می شود و می توانید در کمترین زمان ممکن یک سیستم مستندات با آن طراحی کنید. در این پروژه می خواهیم از همان تم پیش فرض برای پروژه استفاده کنیم.

چرا VuePress؟

VuePress فایل های markdown را به صورت سازمان دهی شده به فایل های Html تبدیل کرده و آنها را در یک فولدر مشخص قرار می دهد تا بعداً مورد استفاده قرار بگیرند.

VuePress در پشت صحنه از Vue و Vue Router برای ایجاد روت های اختصاصی و از webpack برای باندل کردن فایل های اسکریپت استفاده می کند.

تجزیه فایل های markdown به فایل های Vue این امکان را می دهد که بتوانیم از کامپوننت های Vueیی که ایجاد کردیم در فایل های markdown مان استفاده کنیم.

VuePress به خوبی اصول سئو را رعایت می کند و بصورت پیش فرض امکانی را فراهم کرده که توسط آن می توان به پیاده سازی قابلیت تحلیل وب سایت توسط Google Analytics پرداخت.

همچنین یک سیستم جستجو هم وجود دارد که بصورت خودکار تمام هدرها را ایندکس کرده و هنگام جستجو موارد مرتبط را نمایش می دهد.

VuePress بصورت پیش فرض از یک قالب واکنشگرا برای مستندات استفاده می کند و از طرفی این امکان را فراهم کرده تا توسعه دهنده گان قالب های سفارشی را برای سیستم مستندات خود طراحی کنند.

در این پست ما یک سیستم مستندات با همان قالب پیش فرض VuePress ایجاد می کنیم.

پیش نیازها

برای این آموزش، فرض می کنیم که با Html، CSS و جاوا اسکریپت آشنایی دارید. آشنایی با Vue اختیاری است اما در صورت تسلط به آن کمک زیادی به شما می کند.

توجه داشته باشید که آکادمی آنلاین روکسو یکی از بهترین دوره های آموزشی در ارتباط با Vuejs را منتشر کرده است که با کلیک روی لینک زیر می توانید به آن دسترسی داشته باشید:

نصب

برای این پروژه به Node و npm نیاز داریم. دستور زیر را برای اطمینان از نصب بودن آنها در ترمینال وارد کنید.

node -v && npm -v

دستور بالا به ترتیب شماره نسخه Node و npm را نشان می دهد. اگر قبلا آنها را نصب نکرده باشید، می توانید از سایت های رسمی آنها را دانلود و نصب کنید.

در صورتیکه نحوه نصب پلتفرم node و سیستم مدیریت پکیج npm را نیاز دارید لطفا روی لینک زیر کلیک کنید:

در مرحله بعد قصد داریم یک پروژه جدید ایجاد کنیمو دستور بالا را در ترمینال برای ایجاد یک فولدر و تغییر مسیر دایرکتوری به آن وارد کنید.

mkdir scotch-vuepress && cd $_

سپس با دستور زیر یک پروژه جدید در فولدر scotch-vuepress ایجاد کنید.

npm init -y

سپس با دستور زیر vuepress را به صورت محلی نصب می کنیم.

npm install -D vuepress

حال می خواهیم مستندات را مطابق نیازمان سفارشی کنیم و یک سری متن های ساختگی را در آن قرار می دهیم.

ایجاد فایل ها و فولدر های پروژه

هنگام ایجاد پوشه ها در vuepress احتیاط کنید، چون فایل های markdown و فولدرها مطابق با چیدمانی که دارند ارزیابی می شوند.

هر فایل markdown که در یک فولدر قرار گرفته، به یک سند html کامپایل می شود و از طریق فولدر والد میتوان به فایل html دسترسی داشت.

برای شروع یک فولدر به نام docs ایجاد می کرده و تمام فایل های مستندات به همراه فایل های پیکربندی مرتبط با آن را در این فولدر قرار می دهیم.

ابتدا دستور زیر را در ترمینال وارد کنید.

mkdir docs && cd $_

داخل فولدر docs یک فولدر به نام vuepress ایجاد می کنیم و سپس در این فولدر جدید دو فولدر دیگر به نام های counter و guide ایجاد می کنیم.

دقت داشته باشید که به ازای هر کدام از این فولدرها باید یک فایل README.md داشته باشیم.

فولدر counter شامل یک فایل markdown به نام README.md است که پس از تجزیه، به فایل های Html تبدیل می شود. این فولدر صفحه خانگی (home) مستندات مان را نمایش می دهد.

فولدر .vuepress کامپوننت های برنامه را نگهداری می کند.

فولدر dist هم پروژه نهایی که آماده ارسال به سرور است را نگهداری می کند و فایل config.js برای پیکربندی کل سیستم کاربرد دارد.

ایجاد کامپوننت های Vue

در این پروژه مستندات مربوط به یک شمارنده را با استفاده از Vue ایجاد می کنیم.

برای شروع، دو کامپوننت Vue به نام های counter.vue و my-header.vue را ایجاد می کنیم. این کامپوننت ها به عنوان یک کامپوننت شمارنده (counter) و کامپوننت هدر برنامه عمل می کند.

فایل my-header.vue را مطابق زیر ویرایش کنید.

<template>
    <div>
        <h1>This Header is actually a Vue Template</h1>
    </div>
</template>
<script>

</script>
<style scoped>
</style>

سپس فایل counter را مطابق زیر ویرایش کنید.

<template>
    <div class="counter">
        <h1>{{number}}</h1>
        <button @click = "increment">Increment</button>
        <button @click = "decrement">Decrement</button>
    </div>
</template>
<script>
    export default {
        data(){
            return{
                number: 0,
            }
        },
        methods:{
            increment(){
                if(this.number >= 0){
                    this.number++
                }
            },
            decrement(){
                if(this.number > 0){
                    this.number --
                }
            }
        }
    }
</script>
<style scoped>
.counter{
    display: inline-block;
    margin-left: 30%;
}
button{
    display: inline-block;
    padding: 20px;
    margin: 10px;
    font-weight: bold;
    border-radius: 5px;
    box-shadow: 0px 0px 5px 0px rgb(11, 11, 114);
}
h1{
    text-align: center;
}
</style>

این نشان می دهد که ساخت یک شمارنده چقدر راحت است.

ایجاد فایل های markdown

در این مرحله در هر کدام از فولدرهای counter و guide یک فایل markdown ایجاد می کنیم و پس از آن کامپوننت <counter/> را هم در فایل markdown جایگذاری می کنیم.

این فایل ها در آینده تبدیل به صفحات استاتیک می شوند.

همچنین یک فایل README.md برای صفحه خانگی مان نیاز داریم.

برای اینکار درفولدر docs یک فایل به نام README.md ایجاد و کدهای زیر را در آن قرار می دهیم.

---
home: true
actionText: See Counter App
actionLink: /counter/counter-app
features:
- title: Embedded Vue Counter
    details: A Vue counter developed using Vue is embedded in this doc, now that's the power of VuePress!
- title: Fun Docs made with VuePress
    details: This entire doc was basically made with VuePress which parsed markdown files and corresponding assets using webpack.
footer: Developed using VuePress by William Imoh
---

حال باید کامپوننت my-header را در فایل README.md که در بالا ایجاد کردیم قرار دهیم، مانند زیر:

---
home: true
actionText: See Counter App
actionLink: /counter/counter-app
features:
- title: Embedded Vue Counter
    details: A Vue counter developed using Vue is embedded in this doc, now that's the power of VuePress!
- title: Fun Docs made with VuePress
    details: This entire doc was basically made with VuePress which parsed markdown files and corresponding assets using webpack.
footer: Developed using VuePress by William Imoh
---
<my-header></my-header>

تا به اینجا، تمام فایل های markdown مورد نیازمان را ایجاد کردیم، حال باید navigation و sidebar را با استفاده از فایل .vuepress/config.js پیکربندی کنیم.

پیکربندی قالب یا Layout

فایل config.js برای پیکربندی سیستم مستندات استفاده می شود. همان طور که در کدهای زیر می بینید، هنگام ایجاد یک قالب سفارشی، یک آبجکت که شامل فیلدهای مورد نیازمان است را Export می کنیم.

module.exports = {
    title: 'Scotch VuePress',
    description: "A demo documentation using VuePress",
    themeConfig:{
        nav: [
            { text: 'COUNTER', link: '/counter/' },
            { text: 'GUIDE', link: '/guide/' },
        ],
        sidebar: [
            {
                title: 'Counter',
                collapsable: false,
                children: [
                '/counter/counter-app'
                ]
            },
            {
                title: 'API Guide',
                collapsable: false,
                children: [
                    '/guide/guide',
                    '/guide/api'
                ]
            }
            ]
    }
}

ابتدا عنوان وب سایت را مشخص می کنیم و یک توضیحات برای رعایت اصول SEO به آن اضافه می کنیم. این عنوان و توضیحات  ورودی به طور خودکار یک سیستم جستجوی ایندکس شده را روی وب سایت به همراه یک فیلد برای جستجو ایجاد می کند.

در ادامه این اسکریپت آبجکت themeConfig را داریم که  پارامترهای ضروری را برای پیاده سازی قابلیت های مهم روی تم اجرا می کند.

برای ایجاد یک nav bar، یک آرایه nav که متن منوها را مشخص می کند به همراه مسیر هر کدام از این عنصرهای nav داریم،

افزودن پروپرتی collapsible به sidebar باعث ایجاد یک منوی واکنش گرا می شود و بسته به اندازه صفحه نمایش می تواند اندازه اش را وفق بدهد.

حال که همه چیز را تنظیم کردیم، باید سرور را اجرا کنیم:

vuepress dev docs

با اجرای کد بالا، برنامه در پورت 8080 باز می شود.

اگر موقعی که سرور در حال اجراست اقدام به ساخت کامپوننت های Vue بکنید، باید یکبار سرور را ریستارت کنید تا کامپوننت ایجاد شده اعمال شود.

ما توانستیم برنامه را روی سرور محلی اجرا کنیم، اما هدف مان انتشار سایت روی یک سرور واقعی است.

برای اینکار فایل package.json را مطابق زیر ویرایش کنید

{
    "name": "scotch-vuepress",
    "version": "1.0.0",
    "description": "",
    "main": "index.js",
    "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
    },
    "keywords": [],
    "author": "",
    "license": "MIT",
    "devDependencies": {
    "vuepress": "^0.5.0"
    }
}

برای ساخت فایل های استاتیک، دستور زیر را اجرا کنید.

npm run docs:build

بعد از اجرای کد بالا، فایل های استاتیک ایجاد شده در مسیر .vuepress/dist قرار می گیرند.

تغییر استایل

Vuepress از فایل های استاتیک و asset های webpack پشتیبانی می کند و قبل از ساخت برنامه بررسی می کند که url نسبت داده شده به یک asset در فایل markdown درست تنظیم شده باشد.

در این پروژه قصد داریم رنگ های استایل پیش فرض را کمی تغییر دهیم.

برای اینکار یک فایل جدید به نام override.styl در مسیر docs/.vuepress ایجاد می کنیم.در صورتی که مستندات رسمی vuepress را مشاهده کنید، می بینید که به هر متغیر یک رنگ نسبت داده شده است. برای اینکه رنگ را تغییر دهیم باید فایل override.styl را ویرایش کنیم. در این مثال قصد داریم رنگی که به متغیر accentColor نسبت داده شده است را تغییر دهیم.

   $accentColor = #cfa809
    $textColor = #2c3e50
    $borderColor = #eaecef
    $codeBgColor = #282c34

سرور توسعه را با کدهای زیر ریستارت کنید:

npm run docs:dev

انتشار سایت در Netlify

 حال قصد داریم سایت استاتیک مان را با استفاده از Netlify منتشر کنیم. Netlify یک گزینه یکپارچه سازی مداوم و عالی را با Github و یا هر نوع ارائه دهنده کنترل نسخه ارائه می دهد.

برای انتشار سایت روی Netlify مراحل زیر را دنبال کنید:

قدم 1:  یک اکانت روی گیت هاب و Netlify ایجاد کنید. سپس کدهایتان را توسط ابزار git به اکانت گیت هاب push کنید.

قدم 2: به اکانت Netlify تان لاگین کنید و گزینه New Site from Git را انتخاب کنید.سپس گیت هاب را به عنوان فراهم کننده ریپازیتوری مستندات تان انتخاب کنید.

قدم 3: سپس شاخه (branch) یی که می خواهید برنامه در آن منتشر شود را انتخاب کنید.

سپس دستور npm run docs:build را اجرا کنید. به این ترتیب فایل های نهایی مستندات در مسیر docs /.vuepress / dist منتشر می شود. پس از آن روی Deploy Site کلیک کنید.به این ترتیب وب سایت تان درکمترین زمان ممکن، منتشر می شود.

نتیجه گیری

سایت های استاتیک از نظر سرعت، امنیت و قابلیت های نگهداری انتخاب خوبی هستند. در این پست یک وب سایت مستندات استاتیک را ایجاد کردیم که در یک برنامه تک صفحه ای و با VuePress انجام شد. VuePress امکان نوشتن اسکریپت های Vue را در فایل های markdown به شما می دهد، که اینکار باعث افزایش انعطاف پذیری این فریمورک شده و همچنین باعث پویایی سیستم مستندات طراحی شده می شود.