شروع

نصب

میرا برای نصب به پرل نسخه 5.12 به بالا نیاز دارد

برای تست این که پرل را روی سیستم خود از قبل نصب شده دارید یا نه، terminal یا command line را باز کنید و تایپ کنید perl -v اگر پرل از قبل نصب شده باشد متنی شبیه به این را خواهید دید که ورژن پرل نصب شده را به شما نشان خواهد داد

This is perl 5, version 24, subversion 1 (v5.24.1)

اگر پرل را ندارید از این طریق آن‌را نصب کنید:

ویندوز

اگر از ویندوز استفاده میکنید Strawberry Perl یا «پرل توت فرنگی» را ابتدا نصب کنید
توت فرنگی cpan minus را به شکل توکار همراه خود دارد، برای نصب میرا تایپ کنید:

cpanm Mira

سیستم‌های شبه یونیکس

لینوکس

توزیع‌های لینوکس به شکل توکار پرل را در خود دارند، اما اگر نیاز به نصب مجدد یا نصب نسخه‌ی بالاتری که در توزیع شما نصب نیست دارید به این صفحه مراجعه کنید getperl
اگر capan minus را ندارید آن‌را نصب کنید

curl -L https://cpanmin.us | perl - --sudo App::cpanminus

و بعد برای نصب میرا

sudo cpanm Mira

مک

مک به شکل توکار پرل را در خود دارد، اما اگر نیاز به نصب مجدد یا نصب نسخه‌ی بالاتری که در حال حاضر بر روی کامپیوترتان نصب نیست دارید به این صفحه مراجعه کنید getperl

اگر capan minus را ندارید آن‌را نصب کنید

curl -L https://cpanmin.us | perl - --sudo App::cpanminus

و بعد برای نصب میرا

sudo cpanm Mira

شروع

برای شروع به کار با میرا ابتدا یک دایرکتوری جدید با هر نامی که دوست دارید بسازید، این دایرکتوری مکان تمامی محتواها، تنظیمات و قالب‌های سایت شما خواهد بود، وارد مسیر دایرکتوری خود شوید و کار با میرا را شروع کنید

دایرکتوری جدید را می‌توانید هم از طریق کلیک راست در پنجره‌های گرافیکی و انتخاب new folder بسازید و هم از طریق خط فرمان برای شروع مثلا یک دایرکتوری به نام YOUR_Mira را در نظر بگیرید mkdir YOUR_Mira

از طریق خط فرمان وارد مسیر مورد نظر شوید cd YOUR_Mira

به میرا بگویید که در این دایرکتوری پیکربندی شود mira init حالا شما در دایرکتوری خود این‌ها را می‌توانید ببینید

YOUR_Mira/
.
│
├── config
├── config.yml
├── content
├── public
├── statics
├── structure
└── template

توضیح مختصر پیکربندی

config.yml

این فایل حاوی تمام تنظیمات پیش فرض است، با تغییر دادن آن‌ها میتوانید کارکرد سایت خود را تغییر دهید

config

در صورتی که بخواهید هرکدام از طبقات تنظیمات خود را داشته باشد، در دایرکتوری config فایلی به اسم همان طبقه و پسوند yml بسازید، مثلا blog.yml

content

فایل‌های محتوایی که تولید میکنید در دایرکتوری content ذخیره خواهد شد، در اصل خانه اصلی تمام طبقات شما این دایرکتوری است، هر طبقه یک دایرکتوری در این مسیر است، برای مثال در صورتی که چند سایت با نام‌های ,blog, portfolio, projectX, docs بخواهید بسازید مسیر شما به این صورت خواهد بود:

YOUR_Mira/content/
.
│
├── blog
├── docs
├── portfolio
└── projectX

public

فایل‌های استاتیک وبسایت شما که توسط میرا تولید خواهند شد در این مسیر ذخیره می‌شوند، در اصل این دایرکتوری مسیر اصلی وبسایت شما خواهد بود

statics

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

structure

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

template

این دایرکتوری محل ذخیره پوسته‌های ظاهری سایت است

شکل نهایی

در صورتی که چند سایت با نام‌های ,blog, portfolio, projectX, docs بخواهید بسازید، و برای هر کدام بخواهید تنظیمات منحصر به فردی و ساختار جداگانه‌ای نسبت به سایر سایت‌ها در نظر بگیرید، نتیجه چیزی شبیه به این خواهد بود

YOUR_Mira/
.
│
├── config
│     │
│     ├── blog.yml
│     ├── docs.yml
│     ├── portfolio.yml
│     └── projectX.yml
├── config.yml
├── content
│     │
│     ├── blog
│     │     └── _static
│     ├── docs
│     ├── portfolio
│     └── projectX
├── public
├── statics
│     │
│     ├── images
│     ├── css
│     ├── your-theme-statics
│     │      │
│     │      ├── img
│     │      ├── css
│     │      ├── js
│     │      └── static
│     └── logo
├── structure
│     │
│     ├── blog
│     ├── docs
│     ├── portfolio
│     └── projectX
└── template
       │
       ├── default-theme
       ├── another-theme
       └── on-more-theme

اولین نوشته

برای نوشتن هر پست جدید لازم است که تیتر و طبقه‌ای که محتوا در آن تولید میشود با سوییچ های t یا title و سوییچ f یا floor مشخص کنیم، در صورتیکه طبقه را مشخص نکنید پست جدید در طبقه‌ای که به عنوان پیش فرض در تنظیمات مشخص شده ثبت میشود

mira new -t "hello world" -f blog

یا

mira new --title="hello world" --floor=blog

بعد از ساخته شدن اولین پست محتوا با پیغامی شبیه به این روبرو خواهید شد که محل و نام فایل جدید را مشخص می‌کند

/Your_Mira/content/blog/2017-2-11-hello_world.ms created

توجه۱: مسیر فایل در دایرکتوری content مشخص کننده‌ی طبقه‌ی آن برای انتشار است، تغیر مکان آن به معنی تغییر محل قرارگیری برای انتشار نهایی است.

توجه۲: تغییر دادن نام این فایل هیچ مشکلی ندارد، هر طور که خودتان راحت هستید آن‌را تغییر دهید، مثلا به

01-hello.abc

یا

hi.txt

توجه۳: تنها پسوندی که در رفتار فایل‌ها تاثیر میگذارد draft است، هر فایلی با این پسوند از نظر میرا قابل انتشار نیست، از تغییر پسوند تنها برای draft کردن و جلوگیری از انتشار نوشته‌هایتان استفاده کنید.

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

---
utid: 20170212000013
date: 2017-02-12 00:00:13
title: hello world
_index:
_permalink:
categories:
  -
tags:
  -
thumb:
author: kiavash
_markup: markdown
---

قسمت بین دو خط چین --- هدر پست شماست و قسمت بعد از خط چین پایینی بدنه نوشته شما خواهد بود، هر چیزی که میخواهید منتشر شود را در آن بنویسید

توجه: در قسمت هدر به جز فیلد utid و مقدار آن، هر چیزی را که میخواهید ویرایش و هر چیزی را نمیخواهید حذف کنید. اما به utid و مقدار آن دست نزنید، مگر اینکه تمام صفحات راهنما را خوانده باشید و بدانید دقیقا چکار می‌کنید.

---
utid: 20170212000013
date: 2017-02-12 00:00:13
title: hello world
_index:
_permalink:
categories:
  - شروع
  - دسته بندی ۱
  - دسته بندی ۲
tags:
  - سلام
  - شروع
  - برچسب ۱
  - برچسب ۲
thumb:
author: kiavash
_markup: markdown
---
سلام دنیا
این اولین نوشته من است

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

اولین انتشار

حالا که اولین محتوای خود را نوشتیم وقت منتشر کردن آن رسیده

برای انتشار باید طبقات ساختمان میرا را ساخت، برای این کار در خط فرمان تایپ کنید

mira build

تمام شد، صبر کنید تا ساخت تمام شود

حالا به در دایرکتوری public بروید، چیزی شبیه به این را خواهید دید

Your_Mira/public/
.
├── blog
│   ├── 2017
│   │   └── 02
│   │       └── 12
│   │           └── hello-world
│   │               └── index.html
│   ├── archive
│   │   └── 2017
│   │       └── 02
│   │           └── index.html
│   ├── author
│   │   └── kiavash
│   │       └── index.html
│   ├── categories
│   │   ├── دسته-بندی-۱
│   │   │   └── index.html
│   │   ├── دسته-بندی-۲
│   │   │   └── index.html
│   │   └── شروع
│   │       └── index.html
│   ├── tags
│   │   ├── برچسب-۱
│   │   │   └── index.html
│   │   ├── برچسب-۲
│   │   │   └── index.html
│   │   ├── سلام
│   │   │   └── index.html
│   │   └── شروع
│   │       └── index.html
│   ├── feed.xml
│   └── index.html
├── index.html
└── static

اگر بر روی سرور شخصی خود کار میکنید، می‌توانید محتویات دایرکتوری public را در فایل تنظیمات سرور، به عنوان مسیر root دامین خود مشخص کنید، یا اگر از میزبان‌های صفحات ایستا مثل گیت‌هاب پیچ استفاده میکنید، می‌توانید این دایرکتوری را به عنوان مخزن صفحه خود push کنید.

پیش نمایش

برای دیدن یک پیش نمایش از سایت خود بر روی لوکال هاست و با استفاده از مرورگرتان، از سوییچ view استفاده کنید

mira view

پیغامی شبیه به این خواهید دید

HTTP::Server::PSGI: Accepting connections at http://0:5000/

حالا بر روی لوکال هاست و port:5000 سایت شما قابل دسترسی است، مرورگر را باز کنید و در آدرس بار این صفحه را باز کنید:

http://0.0.0.0:5000/
یا
http://127.0.0.1:5000/

در صورتیکه بخواهید سرور پیش نمایش بر روی آدرس یا درگاه دیگری قابل دسترسی شود، از سوییچ های p یا port و سوییچ o یا host اسنفاده کنید

mira view -o 127.0.0.1 -p 1024
یا
mira view --host=127.255.255.254 --port=65535

تنظیمات

درباره فایل‌های تنظیم

میرا، میتواند برای هر طبقه یک فایل تنظیم مجزا داشته باشد یا اینکه تمام طبقات از یک تنظیم مشترک استفاده کنند یا ترکیبی از این دو، یعنی بعضی از طبقات تنظیم شخصی خودرا داشته باشند و بعضی از تنظیمات مرکزی پیروی کنند. فایل تنظیم مرکزی در شاخه اصلی برنامه به نام config.yml ذخیره شده و برای هر طبقه که بخواهید تنظیمات مجزا داشته باشید در شاخه config یک فایل به نام آن طبقه(هم‌نام با شاخه‌ی آن طبقه در شاخه content) با پسوند yml بسازید.
نکته: تعدادی از تنظیمات تنها متعلق به فایل اصلی هستند و تغییر آن‌ها در تنظیمات طبقات نادیده گرفته میشوند، این تنظیمات در ادامه با برچسب مرکزی مشخص میشوند.
توجه: تنظیمات با استاندارد برچسب زنی yaml نوشته میشوند، به فاصله‌ها، کاراکتر خط جدید و هر چیز ظاهری دیگر توجه داشته باشید.
اکثر تنظیمات باید تنها در یک خط نوشته شوند مگر تنظیماتی که به صورت لیستی از نام‌ها یا کلید-مقدار باید مقدار دهی شوند
توجه: لیست‌ها با فرمت YAML باید نوشته شوند: حداقل یک فاصله، یک خط تیره، یک فاصله، نام لیست

title

عنوان سایت شماست، هر طبقه به عنوان یک سایت مجزا میتواند عنوان خود را داشته باشد

description

متنی برای توضیح یا معرفی سایت یا فعالیت‌های آن

author

نام پیش فرض نویسنده یا نویسنده‌ها به عنوان فیلد در هدر نوشته‌ها ظاهر میشود، همچنین در قالب هم به عنوان فیلد author در زیر هر پست، یا به صورت عمومی قابل نمایش است در صورتی که مایل باشید در هر نوشته میتوانید این نام را تغییر دهید، مثلاً اگر نویسنده پیش‌فرض سایت نام خودتان است اما میخواهید مطلب یک نویسنده مهمان را منتشر کنید

email

دقیقاً مانند نام نویسنده، با این تفاوت که در هدر پست هم به صورت پیش‌فرض نمایش داده نمیشود. برای استفاده در هدر یا بدنه قالب

url

آدرس سایت شما، چیزی شبیه به YOURADDRESS.com

در صورتیکه در تنظیمات طبقه وجود نداشته باشید برابر با

YOURADDRESS.com/FLOOR_NAME

خواهد بود

root

دقیقاً مانند url، تنها برای نام شاخه ریشه‌ی شما، مثلاً اگر سایت قرار است در همان ریشه اصلی سایت yoursite.com نمایش داده شود root را با / مقدار دهی کنید، یا اگر قرار است در شاخه‌ی yoursite.com/blog منتشر شود آن را با

/blog/

مقدار دهی کنید.

اگر در تنظیم طبقات وجود نداشته باشد با

/FLOOR_NAME/

برابر خواهد بود.

static

آدرسی که میخواهید محتوای شاخه‌ی statics در ریشه اصلی دایرکتوری سایت شما به آن منتقل شود، مثلاً اگر تصمیم دارید در yoursite.com/static باشد، مقدار را برابر با

/static

اگر در تنظیم طبقات وجود نداشته باشد با

/FLOOR_NAME/static

برابر خواهد بود.

توجه: محتوای شاخه‌ی statics کامل در مسیری که برای این فیلد در config.yml مشخص میکند قرار میگیرد در صورتی که در تنظیمات طبقات این فیلد را مقدار دهی کنید، شاخه‌ای به نام _static در ریشه‌ی طبقه به آدرس مشخص شده منتقل میشود.

imageurl

در حال حاضر تنها یک اشاره‌گر است برای استفاده در قالب به آدرسی که به آن می‌دهید

permalink

فرمتی که میخواهید آدرس یکتای نوشته‌های شما باشد، و از این عناصر می‌تواند بهره ببرد

:year
سال انتشار پست
:month
ماه انتشار
:day
روز انتشار
:title
عنوان پست
:FIELD_NAME
نام هر فیلدی که محتوای تک خطی داشته باشد(لیست نباشد) و در هدر فایل پست با مقدار معتبر وجود داشته باشد

/some/thing/else
هرچیزی که بخواهید به آدرس شما اضافه شود

مثال:

/a/:year/abcd/:month/:chapter/wxyz/:day/else/:title

default_markup

در صورتی که در هدر پست، فرمت مارک‌آپ بدنه را مشخص نکنید، برای آن پست از مقدار این فیلد استفاده خواهد شد، در صورتی که نه در هدر و نه در تنظیمات چیزی را مشخص نکرده باشید به عنوان پیش‌فرض markdown انتخاب خواهد شد

post_num

تعداد پست‌هایی که در صفحه اصلی میخواهید نمایش داده شود، میتوانید یک عدد یا گزینه‌ی all را به عنوان مقدار در نظر بگیرید

post_num: 7
post_num: all

archive_post_num

تعداد پست‌هایی که در صفحه ایندکس هر آرشیوها و برچسب‌ها نمایش داده خواهد شد، میتوانید یک عدد یا گزینه‌ی all را به عنوان مقدار در نظر بگیرید

archive_post_num: 7
archive_post_num: all

post_sort

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

default_floor

اگر هنگام ساختن پست جدید سوییچ f یا floor را انتخاب نکنید، این مقدار به عنوان پیش فرض برای سوییچ در نظر گرفته می‌شود.
برای مثال اگر مقدار را برابر blog قرار دهید، هنگام ساختن پست جدید با این دستور:

mira new -t hello

نوشته جدید با تیتر hello در طبفه blog ایجاد می‌شود.

توجه: فقط تنظیمات مرکزی

template

نام قالبی که میخواهید بر اساس آن صفحات html شما ساخته شوند، این مقدار باید برابر با نام دایرکتوری قالب مورد نظر شما در شاخه‌ی templates باشد

lists

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

lists:
  - categories
  - tags
  - author

namespace

در صورتی که بر اساس فیلدهای خود آرشیو میسازید و میخواهید نام متفاوتی با مقدار آن فیلد برای آدرس در نظر بگیرید در این قسمت آن را مشخص کنید مثال:

namespace:
  veryverylongarchivename : vlan
  آموزش: learn
  کتاب: book
  درباره: about
  شخصی: personal
  ترمینال: terminal

اگر در tag های خود از آموزش استفاده کنید آدرس آن به این صورت خواهد بود yoursite/FLOOR/tag/آموزش/index.html اما اگر در namespace کلید و مقدار

آموزش: learn

را اضافه کرده باشید این آدرس به این صورت تغییر خواهد کرد yoursite/FLOOR/tag/learn/index.html

plugins

نام پلاگین‌هایی که میخواهید فعال باشند

plugins:
  - Jdate

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

default_extension

پسوند فایل‌های محتوای جدید که با استفاده از دستور mira new میسازید، به شکل پیش فرض این پسوند برابر md است، اما میتوانید آن را در این قسمت تغییر دهید

output_extension

هنگام build، فایل‌های خروجی با پسوند html تولید می‌شوند، مقدار دادن به این فیلد، پیش فرض html را تغییر میدهد.

pubishDIR

به شکل پیش فرض دایرکتوری public به عنوان محل ساخته شدن محتوای خروجی در نظر گرفته می‌شود، اما با مقدار دادن به این فیلد، می‌توانید خروجی را تغییر دهید.

برای مثال:

publishDIR: docs

با اضافه کردن خط بالا به config.yml، خروجی را از public به docs تغییر دادیم.

توجه: فقط تنظیمات مرکزی

استفاده از تنظیمات در قالب

هر چیزی که در فایل config.yml وجود دارد در سایت شما با برچسب MAIN و هر کدام از تنظیمات اختصاصی در که در شاخه config دارید در طبقه‌ی خودش با برچسب SITE قابل دسترسی است مثلاً اگر در config.yml فیلد icno را داشته باشیم

{{ MAIN.icon }}

یا اگر در config/books.yml فیلد logo داشته باشیم در تمام صفحات قالب books با این دستور قابل دسترسی است

{{ SITE.logo }}

همانطور که می‌بینید، میتوان از مقادیر config به عنوان مقادیر ثابت استفاده کرد، مثلا آدرس عکس لوگوی سایت را در تنظیمات مقدار دهی کرد:

logo: /static/images/logo.png

و هرجا نیاز بود آن را لود کرد:

<img src ="{{ SITE.logo }}">

همچنین میتوان از لیست‌ها هم به این صورت استفاده کرد، مثلا برای اشاره به آدرس شبکه‌های اجتماعی که میخواهید به آن‌ها لیمک بدهید، فیلدی شبیه به این بسازید:

socials:
 -  link: twitter.com
    name: T_USER_NAME

 -  link: facebook.com
    name: F_USER_NAME

 -  link: github.com
    name: G_USER_NAME

و بعد در قالب به این صورت از آن‌ها استفاده کرد:

{{ FOREACH social IN SITE.social }}
   <a href="{{ social.link }}">{{ social.name }}</a>
{{ END }}

تعدادی از فیلدها به صورت یکتا نیز در قالب تولید میشوند و نیازی به استفاده از پیشوندهای MAIN و SITE برای اشاره به آن‌ها ندارید.

برای اشاره به فیلدهای تنظیمات مرکزی این فیلدها در قالب وجود دارند:

MainTITLE
MainDESCRIPTION
MainURL
MainROOT
MainSTATIC
MainIMAGEURL
MainAUTHOR
MainEMAIL

و برای اشاره به فیلدهای تنظیمات هر طبقه، در قالب‌های ورد استفاده‌ی آن طبقه این فیلدها معتبر هستند:

TITLE
DESCRIPTION
URL
ROOT
STATIC
IMAGEURL
AUTHOR
EMAIL

محتوا

توضیح کلی در باره محتوا

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

محل نگهداری محتوای خام در شاخه‌ی content است، هر دایرکتوری در content یک طبقه‌ی مجزا از داده‌هاست که میتواند تنظیمات، دسته بندی‌ها و قالب خروجی اختصاصی خودش را داشته باشد.برای مثال blog یا document یا هرچیز دیگری. هر فایل موجود در این طبقات، یک محتوای خام قابل انتشار به حساب می‌آید. تنها از فایل‌هایی با پسوند draft چشم پوشی خواهد شد.
همچنین این‌هایل‌ها میتوانند در شاخه‌ی اصلی طبقه یا در زیر شاخه‌هایی با هر عمقی باشند، تنها زیرشاخه‌ای که میرا برای پیدا کردن محتوا در آن جستجو نمی‌کند زیر شاخه‌ی فایل‌های استاتیک است، هر دایرکتوری که با ـ شروع شود به عنوان یک دایرکتوری استاتیک در نظر گرفته میشود

فرض کنید در مسیر content و شاخه‌ی blog بخواهیم دایرکتوری‌های استاتیک را مشخص کنیم:

/content/blog/_static   > copy to >    /public/blog/static
/content/blog/_assets   > copy to >    /public/blog/assets
/content/blog/chapter/_header   > copy to >    /public/blog/chapter/header

میباشد، این نام‌ها در هر عمقی که پیدا شود، میرا وارد آن نمی‌شود.

هر فایل شامل دو بخش header یا سربرگ و body یا بدنه است، بدنه متنی است که میخواهید منتشر شود. در سربرگ هم تنظیمات، مشخصه‌ها و دسته بندی ها را مشخص میکنیم.

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

فیلدهای معنی دار و تاثر گذار در پردازش فایل‌های محتوا

utid
date
title
_index
_markup
_permalink
_type
_layout

سایر فیلدها در سربرگ

لیست‌ها

آرشیو

تولید

برای تولید محتوای جدید از دستور new با فرمت زیر استفاده کنید:

mira new -t "YOUR POST TITLE" -f "blog"

یا

mira new --title="YOUR POST TITLE" --floor="blog"

با پیامی شبیه به این روبرو خواهید شد:

.../YOUR_Mira/content/blog/2017-2-15-YOUR_POST_TITLE.md created

<<<<<<< HEAD <<<<<<< HEAD

یک فایل در مسیر طبقه مورد نظر با پیشوند تاریخ و پسوند md ساخته میشود، نام این فایل تاثیری در نتیجه خروجی نخواهد داشت، پس با خیال راحت و هر طور که دوست دارید میتوانید نام این فایل را تغییر دهید.

یک فایل در مسیر طبقه مورد نظر با پیشوند تاریخ و پسوند pen ساخته میشود، نام این فایل تاثیری در نتیجه خروجی نخواهد داشت، پس با خیال راحت و هر طور که دوست دارید میتوانید نام این فایل را تغییر دهید.

>>>>>>> 0347776e6d46d557843cf9e6b634fdfd3a294582

0347776e6d46d557843cf9e6b634fdfd3a294582

نکته: در صورتی که میخواهید از انتشار یک فایل به شکل موقت چشم پوشی کنید، یا به اصطلاح آن را در درفت نگهداری کنید، تنها کافی است پسوند این فایل را به draft تغییر دهید، به این شکل محتوای شما با تمام خصوصیاتش حفظ خواهد شد، تنها در لیست انتشار قرار نمیگیرد.

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

---
HEDER
FIELDS
---
CONTENT BODY
CONTENT BODY
CONTENT BODY
...
...
...

سربرگ

تیتر، مشخصات، تنظیمات و هر خصوصیت دیگری که بخواهید به یک نوشته اختصاص دهید در قسمت سربرگ نوشته می‌شود، تعدادی فیلد در هر سربرگ به صورت پیش فرض تولید میشود، مابقی را میتوانید به صورت دستی به هر نوشته اضافه کنید یا فایلی همنام هر طبقه در شاخه structure بسازید و فیلدهایی که میخواهید با دستور new در سربرگ هر پست از یک طبقه خاص به صورت اتوماتیک تولید شوند را مشخص کنید

بدون توجه به وجود فایل استراکچر این فیلدها همیشه هنگام ساختن پست جدید در سربرگ ظاهر میشوند

utid
date
title

utid

این فیلد از نظر سیستمی مهمترین فیلد هر نوشته میباشد، ترتیب نمایش، محل ذخیره در حافظه، آدرس دهی و هر چیزی که به محتوای شما مربوط باشد به این فیلد وابسته است. در صورتی که این فیلد موجو نباشد، میرا از تمام محتوای موجود چشم پوشی میکند.
کلمه‌ی utid در اصل مخفف unique time ID میباشد، همانطور که از نام فیلد هم میتوان دریافت، این فیلد یک مشخصه یکتا است که براساس زمان تولید شده

به شکل پیش فرض و در هنگام ساختن هر پست جدید یک شناسه چهارده رقمی از کنار هم قرار دادن سال، ماه، روز، ساعت، دقیقه و ثانیه تولید هر پست به عنوان مقدار این فیلد تولید میشود.
ترتیب تولید و نمایش نوشته های شما در سایت بر اساس مقدار این فیلد ترتیب دهی خواهند شد.
همچنین هنگامی که آدرس ایستای یک محتوا تولید میشود در صورتیکه دو محتوا نام یکسانی به خود بگیرند، اولویت دریافت نام با نویسه‌ای است که utid کوچکتری داشته باشد و پست‌های بعدی در آدرس، پیشوند ۲، ۳،... میگیرند برای مثال اگر دو پست با شناسه‌های 20170203040506 و 20171213141516 اما با تیتر یکسان hello داشته باشیم و فرمت تولید نام های خروجی را هم

:year/:title

تعیین کرده باشیم، خروجی چیزی شبیه به این خواهد بود

YOURSITE.com/blog/2017/hello/          > utid 20170203040506
YOURSITE.com/blog/2017/hello/2/        > utid 20171213141516

همانطور که گفته شد، به شکل پیش فرض و در هنگام ساختن هر پست جدید یک شناسه چهارده رقمی از کنار هم قرار دادن سال، ماه، روز، ساعت، دقیقه و ثانیه تولید هر پست به عنوان مقدار utid اختصاص داده میشود، اما باید به این نکته اشاره کنم که هیچ اجباری در حفظ این فرمت وجود ندارد و تا زمانی که مقادیر utid تکراری نشود به هر شکل که بخواهید میتوانید utid را ویرایش کنید، تنها به این نکته دقت کنید که میرا مقادیر عددی را برای این فیلد میخواند، پس اگر به utid مقداری شبیه به این بدهید:

s1-c3/p145(l3)

هنگام پردازش، میرا آن را به این صورت خواهد خواند

از آنجا که با تغییر دادن utid ترتیب نمایش پست‌های شما هم تغییر میکند، با تغییر این گزینه میتوانید به بازچینی خروجی محتوای خود دست بزنید
مثلا اگر میخواهید نوشته ای به وبلاگ خود اضافه کنید اما مایل نیستید در صفحه اول نمایش داده شود یا مثلا میخواهید در آخرین صفحه وبلاگ و در کنار نوشته‌های اولیه‌تان قرار بگیرد، با تغییر این مقدار میتوانید به خواسته خود برسید، یا برعکس اگر برای نگه داشتن همیشگی یک نوشته در صفحه اول، اگر نمیخواهید از کدها و برچسب‌های موجود برای تولید قالب استفاده کنید، خیلی ساده میتوانید مقدار خیلی بزرگی مثل ۹۹۹۹۹۹۹۹۹۹۹۹۹۹۹۹۹۹۹۹۹۹۹۹۹۹۹۹۹۹۹۹۹۹۹ را به utid اختصاص دهید، اینظور میتوانید مطمین باشید آن نوشته همیشه در بالای سایت شما قرار میگیرد.

توصیه: به جز مواقع ضروری یا زمان‌هایی که احیانا نیاز به ماجراجویی و تجربه دارید، مقدار این فیلد را تغییر ندهید

date

تاریخ تولید فایل محتوا

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

YYYY-MM-DD HH:MM:SS
YYYY-MM-DDTHH:MM:SS

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

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

در قالب درون حلقه‌ی POSTS با این برچسب قابل دسترسی است

{{ date }}

title

تیتر یا عنوان نوشته شما

وجود این فیلد هم مانند utid ضروری است و باید حتما مقدار دهی شود. اما بر خلاف utid، در صورت عدم وجود، میرا از پست چشم پوشی نمیکند، بلکه مقدار title را با عدد utid مساوی قرار می‌دهد.

علاوه بر استفاده به عنوان تیتر نوشته در صفحات ایستا و هدرهای html، برای ساخت آدرس ثابت هر پست هم از این مقدار استفاده میشود، برای مثال اگر عنوان پست شما و فرمت مورد نظرتان برای تولید آدرس اینها باشد:

title: 3rd Hel-lo World :)
:year/:month/:title

در نهایت آدرس یکتای این پست این خواهد بود:

ADDRESS.COM/FLOOR/2017/02/3rd-hel-lo-world/

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

قابل بازیابی در قالب درون حلقه‌ی POSTS با این برچسب

{{ title }}

_index

همانطور که در مورد فیلد title خواندید، آدرس نهایی پست شما با استفاده از آن ساخته خواهد شد، اما در صورتیکه عنوان بیش از حدی که مایل باشید طولانی باشد و نخواهید آدرس طولانی داشته باشید، یا از چیزی به جز اعداد و حروف نوشتاری در عنوان استفاده کردید که وجودشان برای مفهوم بودن معنی ضروری است و میخواهید در آدرس از نام آنها به جای علامتشان استفاده کنید(مثلا به جای * در تیتر، در آدرس بنویسید star) یا حتی تیتر به زبان فارسی نوشته شده اما میخواهید آدرس به انگلیسی ساخته شود، میتوانید از این فیلد کمک بگیرید.

برای مثال اگر عنوان پست شما چیزی شبیه به این باشد:

یک تیتر خیلی خیلی طولانی در مورد هتل‌های ۵* در سفر به آسیا

آدرس نهایی چیزی شبیه به این خواهد بود

ADDRESS.COM/FLOOR/2017/02/یک-تیتر-خیلی-خیلی-طولانی-در-مورد-هتل‌های-۵-در-سفر-به-آسیا/

حالا اگر به _index مقداری شبیه به این بدهیم:

_index: 5start hotels

آدرس به این صورت تغییر خواهد کرد

ADDRESS.COM/FLOOR/2017/02/5star-hotels/

این فیلد در صورت عدم نیاز میتواند خالی بماند یا حذف شود

توجه: اگر صفحات شما در الگویی که تنها حاوی نام تیتر است تولید می‌شوند:

/:title/

از این نام‌ها برای تیتر یا ایندکس استفاده نکنید

archives
page
نام هر فیلدی که در لیست‌های آرشیو مشخص کرده اید، مثل
categories, tags...

author

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

قابل بازیابی در قالب در حلقه‌ی POSTS با استفاده از این برچسب:

{{ author }}

_markup

فرمتی که با آن بدنه محتوا را مینویسید، یا همان markup language. به شکل پیش فرض با مقداری که به فیلدی با نام default_markup در فایل تنظیمات مشخص کرده‌اید پر خواهد شد، اما برای هر پست میتوانید آن را تغییر دهید.
اگر در فایل تنظیمات مقداری برای این فیلد مشخص نکرده باشید و در سربرگ هم به آن مقداری ندهید میرا به شکل پیش فرض از markdown برای پردازش نهایی استفاده میکند.

مقادیری که میرا برای این فیلد می‌شناسد، این‌ها هستند:

markdown
md
textile
bbcode
html
text
txt

مقادیر md و markdown یکی هستند، همچنین txt و text نیز یکی هستند. اگر میخواهید فقط از کدهای html در بدنه‌ی نوشته‌تان استفاده کنید و مقدار را برابر html قرار دهید، دقیقا همان متنی که در بدنه نوشته اید به همان شکل در فایل خروجی نیز استفاده خواهد شد اگر از text یا txt به عنوان مقدار استفاده کنید دقیقا همان متن در خروجی استفاده میشود تنها در انتهای هر خط کاراکتر خط جدید به
تبدیل خواهد شد. استفاده از کدهای html در این حالت نیز مجاز است.

_permalink

در حالت پیش فرض آدرس ایستای هر نوشته با مقداری که به فیلد permalink در فایل تنظیمات داده‌اید ساخته میشود، با مقدار دهی به این فیلد مقدار موجود در فایل تنظیمات نادیده گرفته میشود و از این مقدار استفاده خواهد شد.
برای تنظیم این فیلد، دقیقا از همان مقادیری که برای فیلد permalink در فایل تنظیمات توضیح داده شده می‌توانید استفاده کنید.

_layout

میرا برای تولید خروجی نهایی تمام پست‌ها، به شکل پیش فرض از فایلی به نام post.tt2 در پوسته‌ای که در تنظیمات مشخص کرده‌اید استفاده می‌کند، اما اگر به این فیلد مقدار بدهید، پست مورد نظر، از یک قالب اختصاصی می‌تواند استفاده می‌کند.

_type

در صورتیکه در هر پست به این فیلد مقدار page بدهید، پست مورد نظر، در صفحات اول سایت و کلیدهای page next و page prev پست‌ها لیست نمیشود.

استفاده از این فیلد و فیلدهای layout و permalink برای ساختن صفحات در سایت مفید هست، برای مثال اگر بخواهید یک صفحه به نام «درباره من» بسازید که در صفحات سایت به صورت سریالی بین سایر نوشته‌ها نمایش داده نشود، میتوانید تنظیماتی شبیه به این در هدر آن داشته باشید

title: درباره من
_type: page
_layout: about.tt2
_index: about
_permalink: /:title/

فیلدهای انتخابی

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

thumbs: address.com/img/image.jpg
source: other.com/post.html

از این فیلدها در قالب در زیر مجموعه‌ی حلقه‌ی POSTS با برچسب‌هایی هم نام همین فیلدها میتوانید استفاده کنید

{{ FOREACH POSTS }}
    <a href="{{ url }}#more>{{ title }}</a>
    {{ author }}
    <img src="{{ thumbs }}">
    <a href ="{{ source }}">منبع</a>
    <div class="content">
        {{ body.less}}
    </div>
{{ END }}

لیست ها

اگر بخواهید فیلدهایی را با مقداری بیشتر از یک آیتم داشته باشید، باید آن‌ها را به صورت لیست‌هایی با این دستور زبان بسازید:

نام فیلد، دونقطه، اینتر، فاصله، خط تیره، فاصله، مقدار

categories:
 - cat1
 - cat2

tags:
 - tag1
 - tag2
 - tag3
 - tag4

آرشیو

در صورتیکه بخواهید بر اساس هر کدام از مقادیر سربرگ آٰشیو بسازید، مثل دسته بندی‌ها و ... باید حتما در فایل تنظیمات در قسمت lists نام فیلد را وارد کنید، مثل tags یا categories یا هر نوع آرشیو دیگری که مایل باشید.
مقادیر آرشیو میتوانند لیست یا تکی باشند.

برای مثال برای ساختن صفحات این اسناد از دو نوع لیست استفاده شده، chapter و tags که در chapter نام دسته‌ای که مطالب در آن نوشته شده به صورت تکی مشخص شده مثل تنظیمات و شروع و در tags، بر چسب هایی که برای هر نوشته در نظر گرفته‌ام، یا همان هش‌تگ ها

استراکچر

گفته شد که در هر سربرگ تعدادی فیلد به صورت پیش فرض وجود دارند و هر تعداد فیلد که بخواهید در زمان نوشتن محتوا میتوانید به سربرگ خود اضافه کنید، اما ممکن است بخواهید تمام محتوای تولید شده در یک طبقه تعدادی فیلد انتخابی را به صورت یکپارچه در خود داشته باشد، اگر بخواهید هر بار که محتوای جدیدی تولید میکنید، این فیلد ها را هم بنویسید، ممکن است کمی حوصله سر بر باشد، یا یک فیلد را موقتا فراموش کنید و در یکی از یربرگ‌ها جا بماند. برای حل این مشکل میتوانید از دایرکتوری structure در شاخه‌ی اصلی برنامه کمک بگیرید.
فایلی هم نام طبقه‌ی مورد نظر در این شاخه بسازید و فیلدهایی که میخواهید در سربرگ آن طبقه باشند را در آن بنویسید. برای مثال این اسناد در طبقه‌ای به نام doc-fa قرار دارند، پس فایل استراکچری به این نام برای آن میسازیم /structure/doc-fa و محتوای فایل را به این صورت ویرایش می‌کنیم

_permalink:
chapter:
chaptername:
tags:
  -

حالا هر بار که از دستور mira new برای طبقه‌ی doc-fa استفاده کنیم، فایلی شبیه به این تولید خواهد شد

---
utid: 20170216003954
date: 2017-02-16 00:39:54
title:
_index:
_permalink:
chapter:
chaptername:
tags:
  - 
author: kiavash
_markup: markdown
---

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

بدنه اصلی محتوا

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

برای نوشتن بدنه می‌توانید از Mrkup Language هایی که میرا پشتیبانی میکند، کدهای html یا متن‌های خالص استفاده کنید

markdown
md
textile
bbcode
html
text
txt

تنها به یاد داشته باشید که برای نمایش صحیح متن، در فیلد _markup در سربرگ هر فایل یا فایل تنظیمات، مشخص کرده باشید که دقیقا از چه مارک‌آپی برای نوشتن متن استفاده کرده‌اید.

قسمت‌های بدنه

بدنه هنگام پردازش به دو قسمت less و more تقسیم میشود، less خلاصه یا توضیحی از متنی است که مینویسید و more شامل تمام متن نوشته شده می‌شود

به شکل پیش فرض میرا ۶۰۰ حرف ابتدایی هر متن را بعد از حذف کردن تمام کدهای HTML که ممکن است در آن نوشته شده باشد و نادیده گرفتن تمام قواعد MarkUPی که استفاده کرده‌اید، به عنوان less مشخص می‌کند، اما در صورتیکه بخواهید مقدار less را می‌توانید خودتان مشخص کنید، کافی است هر جا که خواستید در متن‌تان این عبارت را بنویسید

<!-- more -->

تعداد فاصله ها مهم نیستند، میتوانید اینطور بنویسید

<!--        more               -->

تمام قسمت‌های قبل از آن به عنوان less مشخص می‌شوند، در این حالت کدهای HTML نیز از متن حذف نخواهند شد

خلاصه‌ای از متن
یا همان
less
در این قسمت نوشته شده

<!--     more     -->

ادامه متن
را در این قسمت
مینویسیم
کل متن قبل و بعد از نشانه گذار
به عنوان
more
شناخته خواهد شد

به یاد داشته باشید more شامل تمام متن، قبل و بعد از نشانه گذار می‌باشد.

قالب

پوسته و اجزای تشکیل دهنده

بعد از انجام تمام تنظیمات و تولید محتوا، مطمینا نیازمند خروجی برای محتوای تولید شده خواهیم بود، قالب یا template یا همان پوسته‌های خروجی، به ما برای ساختن ظاهر خروجی مطابق سلیقه و نیازهایمان کمک خواهند کرد.

هر قالب یک دایرکتوری است در شاخه‌ی template از شاخه‌ی اصلی. برای استفاده از قالب ها نام این دایرکتوری را در فایل تنظیمات در مقابل فیلد template وارد کنید.

اجزای اصلی تشکیل دهنده هر قالب، این پنج فایل هستند

/template/THEME/
.
├── archive.tt2
├── atom.tt2
├── index.tt2
├── main.tt2
└── post.tt2

همچنین دایرکتوری به نام include هم در شاخه‌ی پوسته، هنگام پردازش نهایی دیده میشود و اگر بخواهید ماژول‌هایی مانند header یا sidebar در نظر داشته باشید میتوانید در این شاخه آن‌ها را ذخیره کنید.

/template/THEME/
.
├── archive.tt2
├── atom.tt2
├── include
│   ├── footer
│   ├── header
│   ├── navbar
│   ├── sidebar
│   ├── some
│   ├── thing
│   └── else
├── index.tt2
├── main.tt2
└── post.tt2

در کل همان پنج فایل با پسوند tt2 اجزای اصلی تشکیل دهنده یک پوسته هستند و وجودشان الزامیست، تنها باید به این نکته اشاره کرد که آرشیو و post را میتوان به هر تعداد نام دیگر که بخواهید تکثیر کنید، که در ادامه در این مورد هم خواهیم خواند.

اما این پنج فایل چه هستند و چه میکنند؟

main

الگویی است که صفحه‌ی مشترک بین تمام طبقات براساس آن ساخته میشود، یا همان صفحه اصلی که زمان باز کردن سایت در شاخه‌ی پیش فرض دیده میشود. اگر در فایل config.yml مقدار url را برابر SITE.com قرارداده باشید و root را مساوی / تنظیم کنید، main در این صفحه تشکیل میشود:

SITE.com/index.html

index

الگوی سازنده‌ی صفحات اول هر طبقه و صفحات ادامه‌ی صفحه‌ی اصلی، در root هر طبقه ساخته خواهد شد
اگر root در فایل config/blog.yml مساوی با /blog تنظیم شده باشد، index.tt2 الگوی سازنده‌ی این صفحات است

Site.com/blog/
Site.com/blog/page/2/
Site.com/blog/page/3/
Site.com/blog/page/...

post

هر فایل محتوایی که میسازید یک آدرس ثابت و ایستا برای خود دارد، که خروجی آن بر اساس این الگو تولید میشود.
برای مثال ممحتوایی در طبقه blog با این مشخصه ها را در نظر داشته باشید:

_index: 5start hotels
_permalink: :year/:title

خروجی آن در این آدرس تولید میشود

/blog/2017/5star-hotels/

تمام آدرس‌های ثابت محتوای تولید شده از الگویی که در فایل post.tt2 تعریف کرده‌اید برای ساخت استفاده میکنند

یک قابلیت آزمایشی
در صورتیکه در سربرگ پست، فیلد _layout را با نام یک فایل معتبر در شاخه‌ی قالب مقدار دهی کنید، به جای post.tt2 آن پست با استفاده از فایل جدید تولید میشود

_layout: custom_page.tt2

اگر در شاخه‌ی قالب فایل custom.tt2 موجود باشد، به جای post.tt2 از آن استفاده خواهد شد.

atom

فید یا همان feed.xml با استفاده از این الگو ساخته میشود، از آنجا که نحوه‌ی تولید فیدها از یک استاندارد مشخص پیروی میکنند، معمولا نیازی به تغییر ندارد، مگر اینکه بخواهید برای خروجی‌های متفاوتی مثل پادکست یا از این دست آن را بهینه سازی کنید.

برچسب‌های مورد استفاده در پوسته

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

برچسب‌های موجود

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

{{ ROOT }}
{{ TITLE }}
{{ SomeThingElse }}
...

MainTITLE

تیتر اصلی سایت ذخیره شده در فایل تنظیمات مرکزی یا همان config.yml نحوه‌ استفاده:

{{ MainTITLE }}

MainDESCRIPTION

توضیحات اصلی سایت ذخیره شده در فایل تنظیمات مرکزی یا همان config.yml نحوه‌ استفاده:

{{ MainDESCRIPTION }}

MainURL

آدرس اصلی سایت ذخیره شده در فایل تنظیمات مرکزی مقدار بازگشتی برای مثال: YOURSITE.com نحوه‌ استفاده:

{{ MainURL }}

MainROOT

ریشه اصلی سایت ذخیره شده در فایل تنظیمات مرکزی مقدار بازگشتی برای مثال: / نحوه‌ استفاده:

{{ MainROOT }}

MainSTATIC

شاخه فایل‌های ثابت سایت ذخیره شده در فایل تنظیمات مرکزی مقدار بازگشتی برای مثال: /statics نحوه‌ استفاده:

{{ MainSTATIC }}

MainIMAGEURL

شاخه فایل‌های ثابت سایت ذخیره شده در فایل تنظیمات مرکزی مقدار بازگشتی برای مثال: /statics/images نحوه‌ استفاده:

{{ MainIMAGEURL }}

MainAUTHOR

نام نویسنده ذخیره شده در فایل تنظیمات مرکزی نحوه‌ استفاده:

{{ MainAUTHOR }}

MainEMAIL

ایمیل نویسنده نحوه‌ استفاده:

{{ MainEMAIL }}

PageTITLE

تیتر صفحه، در صورتیکه از ماژولی شبیه به header برای لود کردن قسمت بالایی صفحات html به شکل ثابت در تمام صفحات استفاده کنید این برچسب کمک بسیاری برای تگ <title> خواهد کرد، برای مثال در main.tt2 مقداری برابر TITLE و در index.tt2 مساوی FloorTITLE خواهد داشت نحوه‌ استفاده:

{{ PageTitle }}

FLOORS

نام تمام طبقات موجود در سایت به همراه توضیحاتشان و تعداد مشخصی از پست‌ها که در فیلد post_num در فایل تنظیمات مشخص کرده‌اید

مقادیر موجود در این برچسب:

name
description

posts (list)

ش posts شامل تعداد مشخص از آخرین ارسال‌های شماست، تعداد ارسال‌های موجود در این کلید از config.yml و فیلد post_num برداشت میشود.
تمام مقادیری که برای POSTS که در قسمت‌های بعد توضیح داده میشود در مورد لیست posts در Floors نیز قابل استفاده است

نحوه‌ استفاده:

{{ FOREACH FLOORS.values }}
  {{ name }}
  {{ description }}

  {{ FOREACH posts }}
    <h2><a href="{{ url }}">{{ title }}</a><h2>
    <h4>{{ CALENDAR.day }}-{{ CALENDAR.month_name }}-{{ CALENDAR.year }}</h4>
    <p>{{ body.less }}</p>
  {{ END }}

{{ END }}

ENTRIES

کلید-مقداری از تمام محتوای تولید شده در سایت، در مورد کارکرد این برچسب، توضیحات UTIDS را بخوانید

UTIDS

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

این برچسب تنها مختص به main.tt2 میباشد

تمام مقادیر معتبر برای POSTS در زیر این برچسب با اضافه کردن ENTRIES.$id نیز قابل استفاده هستند نحوه‌ی استفاده به همراه ENTRIES

{{ FOREACH id IN UTIDS }}
   <h2><a href="{{ ENTRIES.$id.url }}">{{ ENTRIES.$id.title }}</a><h2>
   <h4>{{ ENTRIES.$id.CALENDAR.day }}-{{ ENTRIES.$id.CALENDAR.month_name }}-{{ ENTRIES.$id.CALENDAR.year }}</h4>
   <p>{{ ENTRIES.$id.body.less }}</p>
{{ END }}

TITLE

تیتر اصلی طبقه، ذخیره شده در فایل تنظیمات طبقه
نحوه‌ استفاده:

{{ TITLE }}

DESCRIPTION

توضیحات طبقه، ذخیره شده در فایل تنظیمات طبقه
نحوه‌ استفاده:

{{ DESCRIPTION }}

URL

آدرس سایتی که طبقه در آن منتشر میشود، ذخیره شده در فیلد url فایل تنظیمات طبقه.

نحوه‌ استفاده:

{{ URL }}

ROOT

آدرس شاخه‌ی ریشه، ذخیره شده در فایل تنظیمات طبقه
نحوه‌ استفاده:

{{ ROOT }}

AUTHOR

نام نویسنده، ذخیره شده در فایل تنظیمات طبقه
نحوه‌ استفاده:

{{ AUTHOR }}

EMAIL

نام نوسنده، ذخیره شده در فایل تنظیمات طبقه
نحوه‌ استفاده:

{{ EMAIL }}

BUILD

اطلاعات زمان ساختن آخرین نسخه از سایت، یا تاریخ زمانی که mira build را اجرا میکنید.

{{ BUILD.date }} : 2017-03-25 18:44:03
{{ BUILD.year }}
{{ BUILD.month }}
{{ BUILD.month_name }}
{{ BUILD.month_abbr }}
{{ BUILD.day }}
{{ BUILD.day_name }}
{{ BUILD.day_abbr }}
{{ BUILD.hour }}
{{ BUILD.minute }}
{{ BUILD.second }}

سایر برچسب‌ها برای آرشیو

میرا برای هر آرشیو، همنام با همان آرشیو، مقداری برای قالب تولید میکند، برای مثال اگر در فایل تنظیمات برای آرشیو ها فیلد categories را به عنوان آٰشیو مشخص کرده باشید، حلقه‌ای به نام CATEGORIES_ARCHIVE نیز در قالب قابل استفاده خواهد بود، یا برای tags، میتوانید از TAGS_ARCHIVE استفاده کنید.

اطلاعات موجود در هرکدام از این مقادیر، شبیه به این خواهند بود

CATEGORIES_ARCHIVE = [
          {
            'name' => "CAT1",
            'url' => "/FLOOR/categories/CAT1namespace/",
            'posts' => [
                         '20170210172431',
                         '20170210174503',
                         '20170210173327',
                         '20170210173313',
                         '20170210173319'
                       ]
          },
          {
            'name' => "CAT2",
            'url' => "/FLOOR/categories/CAT2namespace/",
            'posts' => [
                         '20170210172431',
                         '20170210174503',
                         '20170210173327',
                         '20170210173313',
                         '20170210173319'
                       ]
          },
        ]

برای استفاده از این برچسب‌ها باید در حلقه‌ای که با FOREACH تولید میکنید از آن‌ها استفاده کنید

نحوه استفاده برای فیلد فرضی categories

{{ FOREACH CATEGORIES_ARCHIVE.values }}
  <a href="{{ url }}">{{ name }}</a> - <small>{{ posts.size }}</small><br>
{{ END }}

یا

{{ FOREACH cat IN CATEGORIES_ARCHIVE.values }}
  <a href="{{ cat.url }}">{{ cat.name }}</a> - <small>{{ cat.posts.size }}</small><br>
{{ END }}

همانطور که مشخص است در posts، تمام utid ها برگشت داده شده، پس برای نمایش تک تک فایل‌های موجود در هر دسته میتوان از ENTRIES کمک گرفت

{{ FOREACH CATEGORIES_ARCHIVE.values }}
  <a href="{{ url }}">{{ name }}</a> - <small>{{ posts.size }}</small><br>
  {{ FOREACH id IN posts.sort }}
    <h5><a href="{{ ENTRIES.$id.url }}">{{ ENTRIES.$id.title }}</a></h5>
  {{ END }}
{{ END }}

مثلما به جای id و $id از هر نام دیگری که بخواهید میتوانید استفاده کنید.

main.tt2

برچسب‌های معتبر در این قالب و مقادیرشان.

{{ MainTITLE }}
{{ MainDESCRIPTION }}
{{ MainURL }}
{{ MainROOT }}
{{ MainSTATIC }}
{{ MainIMAGEURL }}
{{ MainAUTHOR }}
{{ MainEMAIL }}
{{ MainPageTitle }}

تنها راه نمایش محتوا در صفحه‌ی main، استفاده از حلقه‌ی FLOORS به صورت مستقل، یا حلقه‌ی ENTRIES و کلیدهای UTIDS می‌باشد.

برای انتشار محتوا در هر سایت از حلقه‌ی POSTS استفاده خواهیم کرد، دقت کنید این حلقه در main معتبر نیست. اما posts به عنوان یک حلقه زیر مجموعه FLOORS معتبر است.

FLOORS

این حلقه تنها به اندازه‌ی مقداری که در فیلد post_num در فایل config.yml مشخص کرده‌اید از محتوای هر طبقه را در خود ذخیره می‌کند. نحوه‌ استفاده:

{{ FOREACH FLOORS.values }}
  {{ name }}
  {{ description }}

  {{ FOREACH post IN posts }}
    <h2><a href="{{ post.url }}">{{ post.title }}</a><h2>
    <h4>{{ post.CALENDAR.day }}-{{ post.CALENDAR.month_name }}-{{ post.CALENDAR.year }}</h4>
    <p>{{ post.body.less }}</p>
  {{ END }}

{{ END }}

UTIDS

کلید نام تمام محتوای موجود در سایت مرتب شده بر اساس مقدار utid هر پست، برابر با utid هر پست، در UTIDS ذخیره شده، برای لود کردن محتوا در برچسب ENTRIES قابل استفاده است.

این برچسب تنها مختص به main.tt2 میباشد

تمام مقادیر معتبر برای POSTS در زیر این برچسب با اضافه کردن ENTRIES.$id نیز قابل استفاده هستند.

نحوه‌ی استفاده به همراه ENTRIES

{{ FOREACH id IN UTIDS }}
   <h2><a href="{{ ENTRIES.$id.url }}">{{ ENTRIES.$id.title }}</a><h2>
   <h4>{{ ENTRIES.$id.CALENDAR.day }}-{{ ENTRIES.$id.CALENDAR.month_name }}-{{ ENTRIES.$id.CALENDAR.year }}</h4>
   <p>{{ ENTRIES.$id.body.less }}</p>
{{ END }}

تمام محتوای تولید شده، نمایش داده خواهند شد، تاکید میکنم، تمام محتوا، اگر در میرا پنج سایت(طبقه) ساخته باشید و در هرکدام ۱۰۰ پست باشد، این کد تمام ۵۰۰ نوشته‌ی شما را به ترتیب مقدار عددی utid نمایش خواهد داد.
برای محدود کردن نمایش تعداد پست‌ها میتوان از کدهای کنترل کننده حلقه استفاده کرد، مثال:

{{ FOREACH id IN UTIDS }}
   do any thing
   {{ LAST IF loop.count == 10 }}
{{ END }}
بعد از ۱۰ بار تکرار حلقه تمام خواهد شد.

index.tt2 و atom.tt2

به جز برچسب UTIDS تمام برچسب‌های main.tt2 در index و atom feed با همان مقادیر معتبر هستند

{{ MianTITLE }}
{{ MianDESCRIPTION }}
{{ MianURL }}
{{ MianROOT }}
{{ MianSTATIC }}
{{ MainIMAGEURL }}
{{ MianAUTHOR }}
{{ MianEMAIL }}
{{ PageTITLE }}

{{ TITLE }}
{{ DESCRIPTION }}
{{ URL }}
{{ ROOT }}
{{ STATIC }}
{{ IMAGEURL }}
{{ AUTHOR }}
{{ EMAIL }}

{{ ARCHIVES}} :
{{ FOREACH archive IN ARCHIVES.pairs }}

برای اطلاعات کامل‌تر در مورد آرشیو ها قسمت اول بخش پوسته ها را ببینید، این برچسب مناسب برای نمایش در سایدبار و امثال آن است. برای ساختن صفحات آرشیو، archive.tt2 از POSTS استفاده می‌کند، کارکرد این برچسب با صفحات archive متفاوت است.

{{ ENTRIES }}
{{ FLOORS }}

archive.tt2

به جز برچسب UTIDS تمام برچسب‌های main.tt2 و index.tt2 در archive با همان مقادیر معتبر هستند

{{ MainTITLE }}
{{ MainDESCRIPTION }}
{{ MainURL }}
{{ MainROOT }}
{{ MainSTATIC }}
{{ MainIMAGEURL }}
{{ MainAUTHOR }}
{{ MainEMAIL }}
{{ MainPageTitle }}

{{ TITLE }}
{{ DESCRIPTION }}
{{ URL }}
{{ ROOT }}
{{ STATIC }}
{{ IMAGEURL }}
{{ AUTHOR }}
{{ EMAIL }}

{{ ArchiveTITLE }}

{{ ENTRIES }}
{{ FLOORS }}

post-template

تمام برچسب‌های index.tt2 در post.tt2 با همان مقادیر معتبر هستند.

تنها برچسب اختصاصی در این الگو PostTITLE است که برابر با نام تیتر نوشته شما یا همان فیلد title در سربرگ میباشد

{{ MainTITLE }}
{{ MainDESCRIPTION }}
{{ MainURL }}
{{ MainROOT }}
{{ MainSTATIC }}
{{ MainIMGURL }}
{{ MainAUTHOR }}
{{ MainEMAIL }}
{{ MainPageTitle }}

{{ TITLE }}
{{ DESCRIPTION }}
{{ URL }}
{{ ROOT }}
{{ STATIC }}
{{ IMAGEURL }}
{{ AUTHOR }}
{{ EMAIL }}

{{ ARCHIVES}} :
{{ FOREACH archive IN ARCHIVES.pairs }}

{{ ENTRIES }}
{{ FLOORS }}

{{PostTITLE}}

نمایش محتوا، با استفاده از POSTS

جهت نمایش محتوا در هر کدام از صفحات باید از حلقه‌ای که مقادیر POSTS را نمایش خواهد داد استفاده کرد.

در تمام صفحات به جز صفحه‌ی main.tt2 برای نمایش محتوا از این حلقه استفاده می‌شود.

{{ FOREACH POSTS }}
   ...
{{ END }}

اطلاعات ذخیره شده در هر POSTS چیزی شبیه به بلوک زیر است، بسته به تنظیم شخصی که انجام دادید، ممکن است فیلدها کمتر یا بیشتر باشند.

'title' => "post title",
'author' => 'kiavash',
'floor' => 'blog',
'body' => {
        'less' => "less body content",
        'more' => "full body content"
       },
'date' => '2017-02-10 17:45:03',
'CALENDAR' => {
           'year' => '2017',
           'month_name' => 'February',
           'day' => '10',
           'month' => '02'
           'jyear' => '1396',
           'jmonth_name' => 'بهمن',
           'jday' => '26',
           'jmonth' => '11'
           'hour' => '17',
           'minute' => '45',
           'second' => '03'
    },
'categories' => {
             "CAT1" => {
                    'name' => "CAT1",
                    'url' => "/blog/categories/CAT1namespace/"
                   },
             "CAT2" => {
                    'name' => "CAT2",
                    'url' => "/blog/categories/CAT2namespace/"
                   }
    },
'other_archive_fields' => {
             "OAF1" => {
                    'name' => "OAF1",
                    'url' => "/blog/categories/OAF1namespace/"
                   },
             "OAF2" => {
                    'name' => "OAF2",
                    'url' => "/blog/categories/OAF2namespace/"
                   },
    },
'url' => "/blog/2017/02/10/post-title/",
'custom_field' => 'value',
'other_field' => 'value',
'else' => 'value',

برای فراخوانی مقدار فیلدها در حلقه‌ی POST:

برای آنهایی که مقدار تک خطی دارند کافی است بین دو آکولاد نامشان را بنویسید، مثل

{{ title }}

فیلدهای تاریخ را با یک نقطه بین CALENDAR و مقداری که مورد نظرتان است مشخص کنید، مثل

{{ CALENDAR.year }}
{{ CALENDAR.month_name }}
...

متن بدنه‌ی محتوا هم مانند فیلدهای تاریخ

{{ body.less }}
{{ body.more }}

لیست‌ها و آرشیو‌ها را در یک حلقه جدید لود کنید

{{ FOREACH categories.values }}
   <a href="{{ url }}">{{ name }}</a>
{{- END }}

یا

{{ FOREACH categories }}
   <a href="{{ value.url }}">{{ value.name }}</a>
{{- END }}

حلقه‌ها در هر بار تکرار یک کاراکتر خط جدید تولید میکنند، خط تیره که ابتدای END میبینید، به حلقه می‌گوید که در همان خط بماند

یک مثال کامل:

{{ FOREACH POSTS }}

   <a href="{{ url }}">{{ title }}</a>

   {{ CALENDAR.day }}&nbsp;{{ CALENDAR.month_name }}&nbsp;{{ CALENDAR.year }}

   {{ CALENDAR.jday | $FarsiNum }}&nbsp;{{ CALENDAR.jmonth_name }}&nbsp;{{ CALENDAR.jyear | $FarsiNum }}

   {{ IF author }}
        {{ author }}
   {{- END }}


   {{ IF categories }}
     {{ FOREACH categories.values }}
       <a href="{{ url }}">@{{ name }}</a>
     {{- END }}
   {{- END }}

   {{ IF tags }}
     {{ FOREACH tags }}
        <a href="{{ value.url }}">#{{ value.name }}</a>
     {{- END }}
   {{- END }}

   {{ body.more }}

{{ END }}

در قسمت تاریخ جهت نمایش اعداد به فارسی از فیلتر

| $FarsiNum‍

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

استفاده از فیلدهای فایل‌های تنظیمات در قالب

تمام فیلدهای موجود در فایل‌های تنظیم را میتوان به پوسته نیز وارد کرد

برای داشتن مقادیر موجود در فایل config.yml از برچسب MAIN و تنظیمات ذخیره شده در شاخه‌ی کانفیگ برای هر طبقه با برچسب SITE در قالب قابل بازیابی هستند.
حتی تمام مقادیری که برچسب مستقل دارند مسث description و ... را نیز میتوان از این راه نیز به قالب وارد کرد.

برای مثال اگر در config.yml فیلد icno را داشته باشیم

{{ MAIN.icon }}

یا اگر در config/books.yml فیلد logo داشته باشیم در تمام صفحات قالب books با این دستور قابل دسترسی است

{{ SITE.logo }}

همچنین فیلدهایی که مانند آرایه یا هش، به شکل لیستی از پشته‌ها ذخیره شده‌اند را هم میتوان با حلقه FOREACH در قالب لود کرد

اگر شبکه های اجتماعی که در آن‌ها عضو هستیم را بخواهیم در ساید بار وبلاگ خود معرفی کنیم، در فایل config/book.yml این مقادیر را اضافه میکنیم:

social:
 -  name: twitter
    url: https://twitter.com/USER_NAME
    desc: Follow me on twitter

 -  name: github
    url: https://github.com/USER_NAME
    desc: Fork me on github

 -  name: google+
    url: https://plus.google.com/USER_NAME
    desc: Follow me on google plus

حالا هر جا که بخواهیم در قالب به این مقادیر دسترسی داشته باشیم با استفاده از حلقه FOREACH خواهیم داشت:

{{ FOREACH social IN SITE.social }}
    <a href="{{ social.url }}">my {{social.name }}</a> - {{ social.desc }}
{{ END }}

اگر فیلد social را در فایل config.yml قرار داده بودیم تنها کافی است در ابتدای حلقه، به جای SITE از MAIN استفاده کنیم:

{{ FOREACH social IN MAIN.social }}
...

parser

پارسرهای داخلی میرا

با استفاده از قواعد درونی parserهای میرا میتوان علاوه بر استفاده از markup برای نوشتن بدنه محتوا، از برچسب‌های درونی میرا نیز استفاده کرد

img

در هر قسمت از فایل محتوایی که با پسوند pen تولید شده، با استفاده از برچسب {{ img }} میتوان یک عکس را در بدنه نوشته لود کرد

قاعده استفاده از آن به این شکل است:

{{ img addres/image.jpg [alt] [title] }}

در این برچسب alt و title اختیاری هستند
هر دو گزینه‌ی alt و title باید بین [] قرار بگیرند
آدرس عکسی که لود میکنید اگر با http:// https:// ftp:// یا هرچیزی مثل این‌ها شروع نشود از فیلد imageurl در فایل تنظیمات طبقه انشعاب میگیرد.

در هر جایی از نوشته که میرا با برچسب بالا مواجه شود آن را با کد html شبیه به این یکی میداند.

<img src="/FLOOR/IMG/address/image.jpg" alt="alt" title="title">

مثلا اگر نوشته شما در طبقه وبلاگ با نام blog قرار دارد و در فایل config/blog.yml مقدار imageurl را مساوی

imageurl: /static/blog/images

قرار داده‌باشید، نتیجه این خواهد بود:

<img src="/static/blog/images/address/image.jpg" alt="alt" title="title">

در صورتیکه img را به این صورت نوشته باشید

{{ img http://addres.com/image.jpg [image alt] [image title] }}

با این کد html برابر خواهد بود:

<img src="http://address.com/image.jpg" alt="image alt" title="image title">

اگر میخواهید پارسر عمل نکند یک \ قبل از } ابتدایی قرار دهید

اگر در بدنه پست بنویسید
\{{ img ... }}
نشان داده خواهد شد:
{{ img ... }}

شروع

ویندوز

سیستم‌های شبه یونیکس

لینوکس

مک

توضیح مختصر پیکربندی

config.yml

config

content

public

statics

structure

template

شکل نهایی

تنظیمات

درباره فایل‌های تنظیم

title

description

author

email

url

root

static

imageurl

permalink

default_markup

post_num

archive_post_num

post_sort

default_floor

template

lists

namespace

plugins

default_extension

output_extension

pubishDIR

محتوا

فیلدهای معنی دار و تاثر گذار در پردازش فایل‌های محتوا

سایر فیلدها در سربرگ

لیست‌ها

آرشیو

>>>>>>> 0347776e6d46d557843cf9e6b634fdfd3a294582

قسمت‌های بدنه

قالب

main

index

archive

post

atom

برچسب‌های مورد استفاده در پوسته

برچسب‌های موجود

MainTITLE

MainDESCRIPTION

MainURL

MainROOT

MainSTATIC

MainIMAGEURL

MainAUTHOR

MainEMAIL

PageTITLE

FLOORS

ENTRIES

UTIDS

TITLE

DESCRIPTION

URL

ROOT

AUTHOR

EMAIL

BUILD

ARCHIVES

سایر برچسب‌ها برای آرشیو

FLOORS

UTIDS

parser

اسناد راهنما برای شروع کار با میرا

شروع