docs/index.md - cloudstack-www - Git at Google

 ---
 title: Website Dev Guide
 ---

 This is a website and blog development guide which can be used as a reference to
 allow technical and non-technical contributors to work with the website for
 adding/editing pages and blog posts.

 Most of the pages and blog posts are written in Markdown, which is like a text
 file usually ending with `.md` extension. These .md files are used by Docusaurus
 (the static-site website framework) to generate HTML-based website so we don't
 have to write HTML by manually.

 You may co-relate with the source of this (Markdown) page at:
 https://github.com/apache/cloudstack-www/blob/main/docs/index.md

 For basic Markdown syntax reference, please refer:
 https://www.markdownguide.org/basic-syntax/

 Refer to the following for Docusaurus supported markdown features:
 https://docusaurus.io/docs/2.x/markdown-features

 ## Working with the Website, Pages and Blogs

 ### Website

 Most of the website configuration such as theme, name, logos, menubar, footer
 etc are configurable using the `docusaurus.config.js` that you can edit here:

 https://github.com/apache/cloudstack-www/blob/main/docusaurus.config.js

 ### Pages

 The various standalone pages are in this directory:

 https://github.com/apache/cloudstack-www/tree/main/src/pages

 Here you can use them as examples, on how to create MD or MDX file that build
 as webpages. You can look at 'learn-more.md' as a reusable page that can be
 included in other pages such as the homepage index.tsx, cloud-builders.mdx etc.

 ### Blog

 To create a new blog, create a directory with naming convention
 `YYYY-MM-DD-slug-url`. In this directory you can put in an `index.md` and other
 assets such as images, pdfs etc. The .blog-template boilerplate can be used from
 here:

 https://github.com/apache/cloudstack-www/tree/main/blog/.blog-template

 Use the provided index.md to specify attribute of your blog such as title, tags
 (categories), authors and the slug (the permalink).

 Having all your blog content and assets in a blog directory makes it easier to
 work with GitHub's editor and allows you to visually contribute changes.

 You may further read https://docusaurus.io/docs/blog for advance changes and
 refer to the misc section on this page for various components that you case use.

 A common use-case is to have a header file and a way to limit how much of the
 post shows up on the blog roll. For this, to add read-more we can add a `<!--
 truncate -->` in your blog post (the index.md file):

 ```
 ...blog content...
 <!-- truncate -->
 ...blog content...
 ```

 ## Contributing Changes using GitHub

 Once you've the boilerplate changes done, the steps are:

 1. If you're a committer, you can edit directly the `main` branch or create a
 GitHub branch (optionally in your personally fork) by heading to the
 [branches](https://github.com/apache/cloudstack-www/branches) page:

 ![](new-branch.png)

 2. You may edit any existing page in the `src/pages` directory or an existing
 blog in the `blog` directory, or add new content. If you do this in
 apache/cloudstack-www repository's `main` branch then creating a pull request
 isn't required.

 3. To add a new page or create a new blog you can also upload files, for example to
 add a blog we can use the `.blog-template`, edit the `index.md` and add any
 assets (such as images and pdfs) in a new directory on our computer (say
 `2023-05-10-test-blog`):

 ![](new-blog-dir.png)

 4. Next, you can drag/drop or select this entire folder in the `blog` directory
 of your newly created GitHub branch
 (https://github.com/apache/cloudstack-www/tree/new-blog-post/blog):

 ![](blog-dir.png)

 And, click the commit button to upload the blog post:

 ![](github-commit-blog.png)

 5. Next, open a pull request to get your PR merged (this isn't required if
 you directly make changes in the `main` branch). To do this, you go to the
 branches list and click on the "New pull request" button that's in front of your
 branch:

 ![](new-pr.png)

 Next, create the pull request:

 ![](open-pr.png)

 6. If you've opened a PR, a GitHub bot will notify you once it has built the
 staging website for you to review your changes:

 ![](github-bot.png)

 Your changes will be made live on the project website once a committer (or
 yourself, if you're one) will merge the pull request: (pro-tip - try to always
 delete your branch after merging)

 ![](pr-merged.png)

 If you're making changes directly on the `main` branch your changes will be made
 live in a few minutes, for you to verify:

 ![](test-blog.png)

 **That's it!**

 ## ToC on blog and website page

 If you don't want table of contents show up on right-side of a page/blog, then
 don't use the Markdown syntax for h2 (##), h3 (###) etc. instead use the HTML
 `<h2>`, `<h3>` etc. which will not show the ToC on a page/blog.

 Further reference: https://docusaurus.io/docs/2.x/markdown-features/toc

 ## Images

 We can specify the path related to the `static/` directory paths, all files
 in static folder are available from the root of the website such as:

 ```
 ![](/img/banner.svg "Example image title")
 ```

 Which results in:

 ![](/img/banner.svg "Example image title")

 Further reference: https://docusaurus.io/docs/2.x/markdown-features/assets

 ## Buttons

 Here are some example for buttons, shapes and sizes which depends on the class
 we use in the `<a>` tags. Note: for files within the website/blog source
 folders, always use a target `_blank`.

 For examples:

 <a class="button button--primary button--sm" href="https://cloudstack.apache.org/" target="_blank">BUTTON</a>
 <br/>
 <br/>
 <a class="button button--primary" href="https://cloudstack.apache.org/" target="_blank">BUTTON</a>
 <br/>
 <br/>
 <a class="button button--primary button--lg" href="https://cloudstack.apache.org/" target="_blank">BUTTON</a>
 <br/>
 <br/>

 Buttons can also have colors depending on the class used, such as:

 <a class="button button--secondary" href="https://cloudstack.apache.org/" target="_blank">BUTTON</a>
 <br/>
 <a class="button button--info" href="https://cloudstack.apache.org/" target="_blank">BUTTON</a>
 <br/>
 <a class="button button--success" href="https://cloudstack.apache.org/" target="_blank">BUTTON</a>
 <br/>
 <a class="button button--warning" href="https://cloudstack.apache.org/" target="_blank">BUTTON</a>
 <br/>
 <a class="button button--danger" href="https://cloudstack.apache.org/" target="_blank">BUTTON</a>

 ## Code Blocks

 Example of code block:

 ```
 # dnf install cloudstack-management
 ```

 ## Using Admonitions

 Refer to https://docusaurus.io/docs/2.x/markdown-features/admonitions


 :::tip

 Some **content** with _Markdown_ `syntax`. Check [this `link`](#).

 :::

 :::info

 Some **content** with _Markdown_ `syntax`. Check [this `link`](#).

 :::

 ## Other Examples

 > This is a quote
 >
 > -By somebody

 In this sentence, here is how you **bold**, *italics* or  ~~strike~~.

 Here is a horizontal line:

 ***

 Here is a list of things:
 - Item1
 - Item2
   - Item3
 - Item4
   - Item 5
   - Item 5
     - Item 5
	---
	title: Website Dev Guide
	---

	This is a website and blog development guide which can be used as a reference to
	allow technical and non-technical contributors to work with the website for
	adding/editing pages and blog posts.

	Most of the pages and blog posts are written in Markdown, which is like a text
	file usually ending with `.md` extension. These .md files are used by Docusaurus
	(the static-site website framework) to generate HTML-based website so we don't
	have to write HTML by manually.

	You may co-relate with the source of this (Markdown) page at:
	https://github.com/apache/cloudstack-www/blob/main/docs/index.md

	For basic Markdown syntax reference, please refer:
	https://www.markdownguide.org/basic-syntax/

	Refer to the following for Docusaurus supported markdown features:
	https://docusaurus.io/docs/2.x/markdown-features

	## Working with the Website, Pages and Blogs

	### Website

	Most of the website configuration such as theme, name, logos, menubar, footer
	etc are configurable using the `docusaurus.config.js` that you can edit here:

	https://github.com/apache/cloudstack-www/blob/main/docusaurus.config.js

	### Pages

	The various standalone pages are in this directory:

	https://github.com/apache/cloudstack-www/tree/main/src/pages

	Here you can use them as examples, on how to create MD or MDX file that build
	as webpages. You can look at 'learn-more.md' as a reusable page that can be
	included in other pages such as the homepage index.tsx, cloud-builders.mdx etc.

	### Blog

	To create a new blog, create a directory with naming convention
	`YYYY-MM-DD-slug-url`. In this directory you can put in an `index.md` and other
	assets such as images, pdfs etc. The .blog-template boilerplate can be used from
	here:

	https://github.com/apache/cloudstack-www/tree/main/blog/.blog-template

	Use the provided index.md to specify attribute of your blog such as title, tags
	(categories), authors and the slug (the permalink).

	Having all your blog content and assets in a blog directory makes it easier to
	work with GitHub's editor and allows you to visually contribute changes.

	You may further read https://docusaurus.io/docs/blog for advance changes and
	refer to the misc section on this page for various components that you case use.

	A common use-case is to have a header file and a way to limit how much of the
	post shows up on the blog roll. For this, to add read-more we can add a `<!--
	truncate -->` in your blog post (the index.md file):

	```
	...blog content...
	<!-- truncate -->
	...blog content...
	```

	## Contributing Changes using GitHub

	Once you've the boilerplate changes done, the steps are:

	1. If you're a committer, you can edit directly the `main` branch or create a
	GitHub branch (optionally in your personally fork) by heading to the
	[branches](https://github.com/apache/cloudstack-www/branches) page:

	![](new-branch.png)

	2. You may edit any existing page in the `src/pages` directory or an existing
	blog in the `blog` directory, or add new content. If you do this in
	apache/cloudstack-www repository's `main` branch then creating a pull request
	isn't required.

	3. To add a new page or create a new blog you can also upload files, for example to
	add a blog we can use the `.blog-template`, edit the `index.md` and add any
	assets (such as images and pdfs) in a new directory on our computer (say
	`2023-05-10-test-blog`):

	![](new-blog-dir.png)

	4. Next, you can drag/drop or select this entire folder in the `blog` directory
	of your newly created GitHub branch
	(https://github.com/apache/cloudstack-www/tree/new-blog-post/blog):

	![](blog-dir.png)

	And, click the commit button to upload the blog post:

	![](github-commit-blog.png)

	5. Next, open a pull request to get your PR merged (this isn't required if
	you directly make changes in the `main` branch). To do this, you go to the
	branches list and click on the "New pull request" button that's in front of your
	branch:

	![](new-pr.png)

	Next, create the pull request:

	![](open-pr.png)

	6. If you've opened a PR, a GitHub bot will notify you once it has built the
	staging website for you to review your changes:

	![](github-bot.png)

	Your changes will be made live on the project website once a committer (or
	yourself, if you're one) will merge the pull request: (pro-tip - try to always
	delete your branch after merging)

	![](pr-merged.png)

	If you're making changes directly on the `main` branch your changes will be made
	live in a few minutes, for you to verify:

	![](test-blog.png)

	That's it!

	## ToC on blog and website page

	If you don't want table of contents show up on right-side of a page/blog, then
	don't use the Markdown syntax for h2 (##), h3 (###) etc. instead use the HTML
	`<h2>`, `<h3>` etc. which will not show the ToC on a page/blog.

	Further reference: https://docusaurus.io/docs/2.x/markdown-features/toc

	## Images

	We can specify the path related to the `static/` directory paths, all files
	in static folder are available from the root of the website such as:

	```
	![](/img/banner.svg "Example image title")
	```

	Which results in:

	![](/img/banner.svg "Example image title")

	Further reference: https://docusaurus.io/docs/2.x/markdown-features/assets

	## Buttons

	Here are some example for buttons, shapes and sizes which depends on the class
	we use in the `<a>` tags. Note: for files within the website/blog source
	folders, always use a target `_blank`.

	For examples:

	<a class="button button--primary button--sm" href="https://cloudstack.apache.org/" target="_blank">BUTTON</a>
	<br/>
	<br/>
	<a class="button button--primary" href="https://cloudstack.apache.org/" target="_blank">BUTTON</a>
	<br/>
	<br/>
	<a class="button button--primary button--lg" href="https://cloudstack.apache.org/" target="_blank">BUTTON</a>
	<br/>
	<br/>

	Buttons can also have colors depending on the class used, such as:

	<a class="button button--secondary" href="https://cloudstack.apache.org/" target="_blank">BUTTON</a>
	<br/>
	<a class="button button--info" href="https://cloudstack.apache.org/" target="_blank">BUTTON</a>
	<br/>
	<a class="button button--success" href="https://cloudstack.apache.org/" target="_blank">BUTTON</a>
	<br/>
	<a class="button button--warning" href="https://cloudstack.apache.org/" target="_blank">BUTTON</a>
	<br/>
	<a class="button button--danger" href="https://cloudstack.apache.org/" target="_blank">BUTTON</a>

	## Code Blocks

	Example of code block:

	```
	# dnf install cloudstack-management
	```

	## Using Admonitions

	Refer to https://docusaurus.io/docs/2.x/markdown-features/admonitions


	:::tip

	Some content with _Markdown_ `syntax`. Check [this `link`](#).

	:::

	:::info

	Some content with _Markdown_ `syntax`. Check [this `link`](#).

	:::

	## Other Examples

	> This is a quote
	>
	> -By somebody

	In this sentence, here is how you bold, italics or ~~strike~~.

	Here is a horizontal line:

	***

	Here is a list of things:
	- Item1
	- Item2
	- Item3
	- Item4
	- Item 5
	- Item 5
	- Item 5