ساختن سیستم مستندات (Documentation) با Vue و VuePress

مستندات خوب بخش مهمی از یک پروژه موفق است ، اما یک سیستم مستندسازی کامل ممکن است بیشتر از آنچه پروژه شما نیاز دارد را شامل شود. در این حالت ، صفحات استاتیک اغلب کاملاً خوب عمل می کنند. در این پست ، ما می خواهیم یک وب سایت مستندات استاتیک ایجاد کنیم که همچنین یک برنامه تک صفحه با استفاده از سازنده استاتیک سایت یعنی VuePress است.
سایت های استاتیک
سایت های استاتیک وب سایتهایی هستند که همانطور که ذخیره شده اند ارائه می شوند. هیچ تعامل مستقیم مشتری-سرور مجازی به جز از سمت برنامه های جاسازی شده شخص ثالث وجود ندارد. تولید کنندگان سایت استاتیک در اینترنت بسیار زیاد هستند و هر یک نسبت به بقیه متفاوت است. برخی از آنها سرعت و دفعات لود را بیش از انعطاف پذیری ترجیح میدهند، و برخی دیگر از قابلیت های بسط یافته حمایت می کنند. سایتهای استاتیک به دلیل افزایش سرعت آنها ترجیح داده می شوند و نبود سرور مجازی احتمال نقص در امنیت را کاهش می دهد.
VuePress دارای یک مولد سایت استاتیک و همچنین یک تم پیش فرض مناسب برای ساخت سریع وب سایت های مستند سازی است. در این آموزش ، ما از تم مستندات پیش فرض برای ساخت سیستم خود استفاده خواهیم کرد.
VuePress
به طور پیش فرض ، VuePress فایل های markdown را همانطور که در پوشه ها شکل گرفته و برای ارائه به فایل های HTML ارسال می شوند، تجزیه میکند. VuePress با ایجاد Vue ، Vue Router برای ایجاد مسیرهای جداگانه ، و webpack برای دارایی های دسته شده به کار می آید. در حین ساخت ، هر فایل markdown به عنوان الگوی Vue تجزیه می شود ، در حالی که دارایی ها توسط یک webpack دسته می شوند. تجزیه فایل های markdown به الگوهای Vue راهی را ایجاد می کند که می توانید برای عبور از اسکریپت های بومی Vue به شکل مولفه های تک فایل استفاده کنید.
VuePress سازگار با سئو است و به طور پیش فرض ابزاری برای اجرای ردیابی تحلیلی با استفاده از Google Analytics در صفحات شما فراهم می کند. همچنین ، VuePress با یک سیستم جستجوی حداقلی همراه است که تمام عناوین موجود در وب سایت را فهرست بندی می کند و در هنگام جستجو آنها را نمایش می دهد.
اگرچه انتقالات VuePress با یک طرح پاسخگوی پیش فرض برای مستندات ، ارسال می شوند ، اما از طرح بندی های سفارشی برای یک ظاهر طراحی شده نیز پشتیبانی می کند. برای این پست ، ما باید یک سیستم مستندسازی حداقلی با استفاده از تم پیش فرض و همچنین ویژگی Vue در Markdown را با استفاده از ساخت یک شمارنده ساده در یک فایل Markdown ، پیاده سازی کنیم.
پیش نیازها
برای این آموزش ، باید دانش اساسی در مورد HTML ، CSS و JavaScript داشته باشید. آگاهی از Vue نیز مفید است اما لازم نیست.
نصب
برای این پروژه به Node و npm مدیر بسته آن نیاز دارید. با اجرای دستور زیر بررسی کنید که آیا آن را در پایانه خود نصب کرده اید:
node -v && npm -v

این دستور به ترتیب نسخه های نصب شده node و npm را نمایش می دهد. اگر نصب نکردید ، می توانید آن را از اینجا دانلود کنید.
سپس ، یک پروژه جدید ایجاد کنید. یک پوشه جدید ایجاد کنید و به آن دیرکتوری تغییر دهید:
mkdir vuepress && cd $_

یک پروژه node جدید را در دیرکتوری vuepress مقداردهی کنید:
npm init -y

به سرعت پروژه جدیدی را چارچوب بندی می کند و یک فایل pack.json ایجاد می نماید.
سپس ، VuePress را بصورت محلی با دستور زیر نصب میکنیم:
npm install -D vuepress

پس از نصب VuePress در پروژه ، همه موارد مورد نیاز خود را دارید ، زیرا VuePress با تم مستندات پیش فرض استفاده شده برای این پروژه ارسال می شود. با این حال ، می خواهیم مستندات را متناسب با نیاز خود تنظیم کنیم ، بنابراین در محله بعد پوشه ها و فایل ها را با متن ساختگی ایجاد خواهیم کرد.
ایجاد پوشه ها و فایل ها
هنگام ایجاد پوشه در VuePress ، مراقب باشید ، زیرا پوشه ها و فایل های علامت گذاری را مطابق ترتیب آنها ارزیابی می کند. هر فایل علامت گذاری به عنوان یک پوشه به یک فایل HTML وارد می شود که مسیر آن پوشه اصلی است.
ابتدا یک پوشه Docs ایجاد کنید تا تمام محتوای و پیکربندی اسناد را در خود جای دهد:
mkdir docs && cd $_

در دایرکتوری Docs ، پوشه .vuepress و پوشه های اسناد را که فایل ها را ذخیره می کند ایجاد کنید – counter و guide.
برای کارکردن این مسیرها ، در هر پوشه به فایل README.md نیاز دارند. این به عنوان یک مسیر هوم به آن بخش ویژه خدمت می کند.
پوشه counter حاوی فایل های نشانه گذاری برای تجزیه و همچنین فایل های پیش فرض README.md برای صفحه اصلی است. پوشه guide حاوی مطالب مشابه با پوشه counter میباشد.
پوشه .vuepress دیرکتوری مولفه ها را در خود جای میدهد، پوشه dist که در build ایجاد شده و فایل config.js که برای پیکربندی سیستم کلی استفاده می شود.
ایجاد مؤلفه های Vue
برای این پروژه ، ما یک شمارشگر ساده با استفاده از Vue می سازیم. دو مؤلفه Vue را با پسوند .vue به نام counter.vue و my-header.vue ایجاد کنید. این مؤلفه ها به ترتیب به عنوان یک مؤلفه شمارنده و یک هدر ساده عمل می کنند. در my-header.vue ، متن vue را ویرایش کنید:
<template>
<div>
<h1>This Header is actually a Vue Template</h1>
</div>
</template>
<script>

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

اسکریپت counter.vue را مانند این ویرایش کنید:
<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>

این مؤلفه شامل همه چیزهایی است که برای شمارنده لازم دارید. در حال حاضر مولفه های Vue آماده استفاده هستند.
ایجاد فایل های Markdown
در مرحله بعد ، فایلهای Markdown را در دایرکتوری counter و guide ایجاد کنید. فایل های Markdown را برای counter و guide ببینید. از Frontmatter برای تنظیم دینامیکی عنوان صفحات جداگانه استفاده می شود. مؤلفه <counter /> نیز در فایل علامت گذاری قرار داده شده است.
این فایل ها بعداً به صفحات استاتیک تبدیل می شوند. برای صفحه اصلی خود ، همچنین نیاز به یک فایل Markdown با عنوان README.md داریم تا به عنوان صفحه اصلی ارائه شود. Frontmatter در فایل های Markdown برای تنظیم برخی از ویژگی های پویای صفحه اصلی استفاده می شود. یک فایل EADME.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 Vue را در مسیر هوم قرار دهید. فایل 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 را دارید. بیایید پیکربندی ناوبری و نوار کناری (sidebar) را با استفاده از .vuepress / config.js انجام دهیم.
پیکربندی طرح بندی
فایل config.js برای شخصی سازی سیستم مستندات استفاده می شود. در ایجاد این سیستم سفارشی ، یک آبجکت که شامل فیلدهای مورد نیاز است صادر می کنیم:
module.exports = {
title: ‘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’
]
}
]
}
}

ابتدا عنوان وب سایت را مشخص می کنیم و توضیحی را به آن اختصاص می دهیم که برای سئو خوب باشد. این عنوان و توضیحات به طور خودکار یک سیستم جستجوی فهرست شده را در وب سایت با نوار جستجو ارائه می دهد.
مورد بعدی در اسکریپت ، آبجکت themeConfig است که پارامترهای مورد نیاز برای اجرای برخی عملکردهای خاص در تم را دریافت می کند. برای ایجاد نوار ناوبری ، یک آرایه nav ایجاد می کنیم که حاوی آبجکت های مشخص کننده متن و مسیر نمایش هر عنصر nav می باشد. می توانید اطلاعات بیشتری درباره پیکربندی تم پیش فرض را در اینجا مشاهده کنید.
ما از نوارهای کناری طبقه بندی شده استفاده کرده ایم تا کاربران بتوانند هر لحظه در مستندات ، نگاهی سریع به منو داشته باشند. با استفاده از ویژگی collapsable در گروه نوار کناری ، می توان منوی نوار کناری را به طور پیش فرض روی collapse تنظیم کرد. در اینجا می توانید اطلاعات بیشتری را در نوار کناری بیابید.
اکنون همه چیز تنظیم شده است ، برای شروع یک سرور مجازی توسعه ، دستور زیر را اجرا کنید:
vuepress dev docs

سرور مجازی dev محلی در پورت 8080 میزبانی می شود. VuePress با ویژگی لود مجدد جدید ، اجرای هرگونه تغییر در برنامه را در حین توسعه اعمال می کند.
اگر مؤلفه های Vue در حالت لایو بودن سرور مجازی توسعه محلی ایجاد شوند، ریستارت سرور مجازی توسعه لازم خواهد بود.

اکنون که ما یک سرور مجازی dev در حال اجرا داریم، هدف استقرار سایت خواهد بود. برای تمیز کردن مسائل ، فایل package.json را ویرایش کنید تا شامل دستورات توسعه و همچنین دستورات ساخت باشد. فایل package.json را ویرایش کنید:
{
“name”: “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 از فایل های استاتیک و همچنین دارایی های webpack پشتیبانی می کند و توجه میکند که از صحت URL اختصاص داده شده به یک دارایی در نشانه گذاری قبل از ساخت اطمینان حاصل شود. برای مورد ما ، فقط باید رنگ پایه را کمی تغییر دهیم. ما با استفاده از سبک ها رنگ های پیش فرض را باطل می کنیم.
یک فایل جدید به نام override.styl را در Docs / .vuepress ایجاد کنید. در حالی که از اسامی متغیر اختصاص داده شده به رنگ مطابق مستندات رسمی استفاده می کنیم ، اسکریپت override.styl را ویرایش می کنیم تا accentColor را با موارد زیر تغییر دهیم:
$accentColor = #cfa809
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34

سرور مجازی توسعه را با دستور زیر مجدد راه اندازی کنید:
npm run docs:dev

توجه داشته باشید که تغییرات ایجاد شده در فایل استایل بلافاصله در مرورگر منعکس می شود.
اکنون سیستم مستندات را با صفحات جداگانه تکمیل کرده ایم.
به کار بردن Netlify
در مرحله بعدی با استفاده از Netlify سایت استاتیک را مستقر می کنید. Netlify با بکارگیری Github یا هر ارائه دهنده کنترل نسخه میزبانی و پشتیبانی شده ، گزینه ادغام مداوم را فراهم می کند. برای استقرار سایت خود در Netlify این مراحل را دنبال کنید:
گام 1
در Github و Netlify یک حساب کاربری ایجاد کنید. کد خود را با استفاده از Git به Github وارد کنید.
گام 2
وارد حساب Netlify خود شوید و گزینه ” New site from Git ” را انتخاب کنید. Github را به عنوان ارائه دهنده توسعه مداوم انتخاب کنید و منبع حاوی مستندات را انتخاب کنید.
گام 3
شعبه را تعیین کنید تا به عنوان master مستقر شوید یا هر شعبه ای را که می خواهید مستقر کنید انتخاب کنید. دستور build را روی npm run docs:build تنظیم کنید: دایرکتوری انتشار را روی docs/.vuepress/distقرار دهید. روی ” Deploy Site” کلیک کنید. وب سایت شما باید در زمان کمی مستقر شود و یک URL عمومی برای دسترسی به آن فراهم گردد.
در اینجا نسخه مستقر شده از این آموزش در Netlify وجود دارد.
نتیجه
سایت های استاتیک به دلیل سرعت ، امنیت و قابلیت نگهداری مفید هستند. در این آموزش ما با استفاده از VuePress یک وب سایت مستندات استاتیک ایجاد کردیم که یک برنامه تک صفحه ای نیز میباشد. VuePress انعطاف پذیری نوشتن اسکریپت های Vue را در داخل فایل های Markdown ارائه می دهد که پویایی را به سایت های استاتیک ارائه می کند. به راحتی پروژه را اصلاح کنید تا چندین پوشه و فایل های markdown مربوطه را دربر بگیرید.

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

استفاده از nsh برای دستورات از راه دور اوبونتو 18 – میزبانی وب سایت با Caddy اوبونتو 18

تنظیم سرور ذخیره سازی آبجکت با استفاده از Minio در اوبونتو 18 – ضبط و اشتراک گذاری ترمینال با Terminalizer اوبونتو

تنظیم مسیریابی شرطی و پاسخگو با React Router v4 – ایجاد یک URL کوتاه کننده با Django و GraphQL

یک برنامه ردیابی سلامت را با React ،GraphQL و Okta – ساخت برنامه چت زمان حقیقی React و GraphQL

به روزرسانی فیلترهای مرتب سازی Angular (زاویه ای) – با استفاده از React ، Superagent و API اینستاگرام

نحوه ساختن یک برنامه جهانی با Nuxt.js و Django – دکمه دانلود با ریزتعاملات با CSS ، anime.js و segment.js

نحوه اضافه کردن عکسهای پیشرفته در Node و Express – با Vue ،GraphQL و Apollo Client یک وبلاگ ساخت

یک برنامه SSR با روتر Preact ، Unistore و Preact بسازید – ساخت برنامه های وب پیشرونده با Angular

اشکال زدایی JavaScript در تولید با نقشه های منبع – می توان با Koa برنامه “سلام جهانی” ساخت

ساختن یک برنامه با Node ، React ، Okta – مدیریت حالت فرم در React با Redux Form

نحوه تنظیم Laravel ، Nginx و MySQL – ارتقاء از AngularJS به Angular با ngUpgrade