در این مطلب میخواهیم یک مثال دیگر از PowerShell را به همراه GitHub Actions را بررسی کنیم. هدف ایجاد یک Static Site Generator و در نهایت پابلیش خروجی استاتیک بر روی GitHub Pages است. روالی که در ادامه بررسی میکنیم صرفاً یک مثال از ترکیب این تکنولوژی‌ها است و قاعدتاً روش‌های ساده‌تر و سرراست‌تری نیز برای اینکار وجود دارد. به عنوان مثال میتوانید از Jekyll که یک SSG مبتنی بر Ruby است نیز استفاده کنید که GitHub Pages، به صورت پیش‌فرض از آن پشتیبانی میکند. در اینحالت به محض پوش کردن سایت بر روی ریپوزیتوری (با فرض اینکه این امکان را فعال کرده باشید) به صورت خودکار سایت بیلد شده و خروجی بر روی یک برنچ دیگر قرار خواهد گرفت و در نهایت برنچ بیلد شده توسط GitHub Pages میزبانی خواهد شد (البته امکان تغییر برنچ پیش‌فرض را نیز دارید). اما اگر بخواهیم کل فرآیند بیلد را به صورت سفارشی انجام دهیم، میتوانیم از GitHub Actions استفاده کنیم؛ یعنی مشابه کاری که Jekyll انجام میدهد. به محض پوش کردن محتوا، یک اسکریپت PowerShell برای اینکار فراخوانی شود و خروجی نهایی بر روی یک برنچ دیگر منتشر شود. خروجی نهایی این چنین قالبی خواهد داشت:
همانطور که در کد فوق مشاهده میکنید، تابع Copy-ToBuild فراخوانی شده است. درون این تابع، ابتدا لی‌اوت‌های موردنیاز برای تولید صفحات HTML را درون یک متغییر با نام layouts قرار داده‌ایم. درون لی‌اوت‌ها یکسری placeholder برای قرارگیری قسمت‌های مختلف سایت تعریف کرده‌ایم که قرار است توسط تابع عنوان شده، جایگزین شوند. در ادامه توسط تابع Get-Posts، تمامی مطالب درون دایرکتوری posts را واکشی کرده و برای هر کدام، صفحه‌ی HTML معادل آن را تولید کرده‌ایم. برای پارز کردن قسمت Front Matter هر بلاگ‌پست نیز از پکیج powershell-yaml استفاده شده‌است. درون تابع Get-Posts باید هر مطلب را همراه با لی‌اوت اصلی سایت، به HTML تبدیل کنیم. بنابراین یکسری عملیات string replacement درون تابع عنوان شده انجام گرفته است. در نهایت، مطالب همراه با لی‌اوت مناسبی درون دایرکتوری build ذخیره خواهند شد و سپس یک لیست از مطالب پارز شده به عنوان خروجی تابع برگردانده خواهد شد. در نهایت درون تابع Copy-ToBuild، یکسری card برای نمایش آخرین مطالب بلاگ تهیه شده، سپس خروجی نهایی درون فایل index.html همراه با قالب اصلی ذخیره خواهد شد.
نکته: در اینجا از فونت آقای راستی‌کردار استفاده شده است؛ با آرزوی بهبودی و سلامتی ایشان.
ساختار پروژه
ساختاری که برای پروژه در نظر گرفته‌ام به صورت زیر است:
├── _layout │ ├── _footer.html │ ├── _header.html │ ├── _nav.html │ └── main.html ├── build ├── img ├── posts └── set-posts.ps1
- دایرکتوری layout_: درون این دایرکتوری، ساختار اصلی بلاگ را قرار داده‌ایم. در ادامه محتویات هر فایل را مشاهده خواهید کرد:
<!--main.html-->
<!DOCTYPE html>
<html dir="rtl">
{{header}}
<body>
{{nav}}
<main>
{{content}}
</main>
{{footer}}
</body>
<!--_header.html-->
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{{title}}</title>
<link href="https://cdn.jsdelivr.net/gh/rastikerdar/samim-font@v4.0.5/dist/font-face.css" rel="stylesheet"
type="text/css" />
<link href="https://cdn.jsdelivr.net/npm/tailwindcss@2.2.16/dist/tailwind.min.css" rel="stylesheet">
<style>
* {
}
</style>
</head>
<!--_nav.html-->
<header>
<nav>
<div>
<div>
<a href="#">بلاگ من</a>
</div>
<div>
<ul>
{{nav}}
</ul>
</div>
</div>
</nav>
</header>
<!--_footer.html-->
<footer>
<div>
<div>
<p>
تمامی حقوق محفوظ است
</p>
</div>
</div>
</footer> - دایرکتوری build: درون این دایرکتوری، خروجی‌های HTML که قرار است توسط اسکریپت PowerShell جنریت شوند، قرار خواهند گرفت. این پوشه در واقع قرار است توسط GitHub Pages میزبانی شود.
- دایرکتوری img: درون این دایرکتوری، تصاویر مربوط به هر بلاگ‌پست را قرار خواهیم داد.
- دایرکتوری posts: درون این دایرکتوری، مطالب‌مان را با فرمت Markdown، قرار خواهیم داد. به عنوان مثال در ادامه یک نمونه از آن را مشاهده خواهید کرد (در کد زیر از Front Matter برای اضافه کردن یکسری متادیتای موردنیاز که حین بیلد شدن ضروری هستند استفاده شده‌است)
--- title: اولین پست من slug: hello date: 2023-04-26 author: سیروان عفیفی tags: [tag1, tag2, tag3] excerpt: این یک پست تستی است در مورد اینکه چطور میتوانیم از این قالب استفاده کنیم --- # اولین پست من ## اولین پست من ### اولین پست من #### اولین پست من ##### اولین پست من ###### اولین پست من لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ و با استفاده از طراحان گرافیک است. چاپگرها و متون بلکه روزنامه و مجله در ستون و سطرآنچنان که لازم است و برای شرایط فعلی تکنولوژی مورد نیاز و کاربردهای متنوع با هدف بهبود ابزارهای کاربردی میباشد. کتابهای زیادی در شصت و سه درصد گذشته، حال و آینده شناخت فراوان جامعه و متخصصان را می‌طلبد تا با نرم افزارها شناخت بیشتری را برای طراحان رایانه ای علی الخصوص طراحان خلاقی و فرهنگ پیشرو در زبان فارسی ایجاد کرد. در این صورت می‌توان امید داشت که تمام و دشواری موجود در ارائه راهکارها و شرایط سخت تایپ به پایان رسد وزمان مورد نیاز شامل حروفچینی دستاوردهای اصلی و جوابگوی سوالات پیوسته اهل دنیای موجود طراحی اساسا مورد استفاده قرار گیرد. <img src="/img/graphql.jpg"/>
همانطور که مشاهده میکنید، مسیر تصویر استفاده شده در بلاگ‌پست، از دایرکتوری img خوانده شده‌است.
- فایل set_post.ps1: موتور اصلی جنریت کردن صفحات HTML این فایل میباشد. در ادامه محتویات آن را مشاهده خواهید کرد. سپس هر کدام از توابع استفاده شده را یکی‌یکی توضیح خواهیم داد:
Function Get-Layouts {
$headerLayout = Get-Content -Path ./_layout/_header.html -Raw
$homeLayout = Get-Content -Path ./_layout/main.html -Raw
$footerLayout = Get-Content -Path ./_layout/_footer.html -Raw
Return @{
Header = $headerLayout
Home = $homeLayout
Footer = $footerLayout
}
}
Function Get-PostFrontMatter($postContent) {
$frontMatter = [regex]::Match($postContent, "(---(?:\r?\n(?!--|\s*$).*)*)\s*((?:\r?\n(?!---).*)*\r?\n---)")
Return $frontMatter
}
Function Set-Headings($postHtml) {
Return $postHtml -Replace '<h(\d) id="(.*)">', {
$level = $_.Groups[1].Value
$id = $_.Groups[2].Value
$class = Switch ($level) {
'1' { 'text-4xl font-bold mb-2' }
'2' { 'text-3xl font-bold mb-2' }
'3' { 'text-2xl font-bold mb-2' }
'4' { 'text-xl font-bold mb-2' }
'5' { 'text-lg font-bold mb-2' }
'6' { 'text-base font-bold mb-2' }
}
"<h$level class='$class' id='$id'>"
}
}
Function ConvertTo-Slug {
[CmdletBinding()]
param(
[Parameter(Mandatory = $true, ValueFromPipeline = $true)]
[string]$String
)
process {
$slug = $String -replace '[^\w\s-]', '' # remove non-word characters except hyphens
$slug = $slug -replace '\s+', '-' # replace whitespace with a single hyphen
$slug = $slug -replace '^-+|-+$', '' # remove leading/trailing hyphens
$slug = $slug.ToLower() # convert to lowercase
Write-Output $slug
}
}
Function Get-Posts {
$markdownPosts = Get-ChildItem -Path ./posts -Filter *.md
$posts = @()
Foreach ($post in $markdownPosts) {
$postContent = Get-Content -Path $post.FullName -Raw
$frontMatter = Get-PostFrontMatter $postContent
$frontMatterObject = $frontMatter | ConvertFrom-Yaml
$slug = $frontMatterObject.slug ?? (ConvertTo-Slug "$($frontMatterObject.date)-$($frontMatterObject.title)")
$body = $postContent.Replace($frontMatter.Value, "") | ConvertFrom-Markdown
$postHtml = $layouts.Home -replace '{{header}}', $layouts.Header `
-replace '{{title}}', $frontMatterObject.title `
-replace '{{nav}}', (Set-Navs) `
-replace '{{content}}', $body.Html `
-replace '{{footer}}', $layouts.Footer
$postHtml = Set-Headings $postHtml
$postHtml | Out-File -FilePath ./build/$slug.html
$posts += @{
title = $frontMatterObject.title
slug = $slug
excerpt = $frontMatterObject.excerpt
date = $frontMatterObject.date
author = $frontMatterObject.author
body = $body.Html
}
}
Return $posts
}
Function Set-Archive {
$posts = Get-Posts
$archive = @()
$archive = @"
<ul>
$($posts | ForEach-Object { "<li><a href='$($_.slug).html'>$($_.title)</a></li>" })
</ul>
"@
Return $archive -join "`r`n"
}
Function Copy-ToBuild {
$layouts = Get-Layouts
$latestPosts = Get-Posts | ForEach-Object { @"
<div>
<img src="https://via.placeholder.com/300x200" alt="$($_.title)">
<h2>$($_.title)</h2>
<p>$($_.excerpt)</p>
<a href="$($_.slug).html">ادامه مطلب</a>
</div>
"@
}
$homeLayout = $layouts.Home -replace '{{header}}', $layouts.Header `
-replace '{{nav}}', (Set-Navs) `
-replace '{{title}}', 'بلاگ من' `
-replace '{{content}}', ('<div>' + $latestPosts + '</div>') `
-replace '{{footer}}', $layouts.Footer
$homeLayout | Out-File -FilePath ./build/index.html
Copy-Item -Path ./img -Destination ./build -Recurse -Force
}
Function Set-Navs {
$navs = @(
@{
title = "صفحه اصلی"
url = "/sample"
},
@{
title = "درباره ما"
url = "/sample/about.html"
},
@{
title = "تماس با ما"
url = "/sample/contact.html"
}
)
$navLayout = Get-Content -Path ./_layout/_nav.html -Raw
$navLayout -replace '{{nav}}', ($navs | ForEach-Object { "<li><a href=""$($_.url)""text-gray-700 hover:text-gray-800 m-2"">$($_.title)</a></li>" })
}
Copy-ToBuild ایجاد GitHub Actions Workflow
در ادامه برای ساختن workflow نهایی باید با کمک GitHub Actions، اسکریپت PowerShellی را که ساختیم، اجرا کنیم. این اسکریپت ابتدا پروژه را clone کرده، سپس وابستگی موردنیاز را نصب کرده و در نهایت اسکریپت را اجرا خواهد کرد:
name: Deploy static content to Pages
on:
push:
branches:
- main
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout Repository
uses: actions/checkout@v2
- name: Install powershell-yaml module
shell: pwsh
run: |
Set-PSRepository PSGallery -InstallationPolicy Trusted
Install-Module powershell-yaml -ErrorAction Stop
- name: Setup Pages
uses: actions/configure-pages@v3
- name: Build Static Site
shell: pwsh
run: |
. ./set-posts.ps1
- name: Upload Static Site Artifact
uses: actions/upload-pages-artifact@v1
with:
path: build
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v2 نحوه انتشار یک مطلب جدید
- درون دایرکتوری posts، مطلب موردنظر را به همراه Front Matter زیر ایجاد کرده و سپس محتویات مطلب را بعد از آن وارد کنید:
--- title: اولین پست من slug: hello date: 2023-04-26 author: سیروان عفیفی tags: [tag1, tag2, tag3] excerpt: این یک پست تستی است در مورد اینکه چطور میتوانیم از این قالب استفاده کنیم --- content
- تغییرات ایجاد شده را کامیت و سپس پوش کنید. به محض پوش کردن تغییرات، GitHub Actions پروسه بیلد را انجام خواهد داد و بلافاصله میتوانید تغییرات را مشاهده نمائید.
نکته: قابلیت GitHub Pages به صورت پیش‌فرض فعال نیست. برای فعال کردن آن ابتدا باید به قسمت تنظیمات ریپوزیتوری GitHubتان مراجعه کرده و سپس از تب Pages، فیلد Source را بر روی GitHub Actions قرار دهید:
بنابراین بعد از پوش کردن تغییرات workflowایی که ایجاد کردیم توسط Source شناسایی خواهد شد و سپس وب‌سایت از طریق آدرس https://<username>.github.io/<repository> در دسترس قرار خواهد گرفت:
کدهای این مطلب را میتوانید از اینجا دریافت کنید.
