# Getting Started

Mophidian provides a cli tool called `moph` to streamline the creation of your website. To start you will want to create a new mophidian project. If you ever want to know what a command does or to know what is possible, use `moph --help` or `moph {command} --help`

For more on the cli tool see the cli section.

## Creating a Project

    moph new {project name}

This will create the project in a new directory with the same name as the project name. Mophidian has also has a preset with a page, layout, and a component. This is a good option if you want an example of how a project can be structured. To use the preset use;

    moph new {project name} -p|--preset

## Development

Now that you have a project you can begin creating your website. The file structure is based on the svelte kit file structure. Each page is in it's own directory and each directory only has one layout. These are the only two pages that have limits per directory. You may write as many static and markdown files in these directories as you want.

You may have noticed that markdown was mentioned. Each markdown file in the source directory, `src/pages` by default, will be rendered to html. Markdown files use the closest layout file as it's base.

Since Mophidian is a route based SSG, each page is an `index.html` file is in it's own directory. There can be multiple markdown files in one directory, so how does that fit into this? Well each markdown files get their own directory equal to the name of the file. `README` markdown files are treated as `index.html` so be careful when placing page and markdown files in the same directory.

You may only have one `page.phml` and `layout.phml` file per directory. `page.phml` files look like this.

    <!-- page.phml -->

    <>
        {Your content here}
    </>

    <!--       or       -->

    <{html-tag}>
        {Your content here}
    </{html-tag}>

while `layout.phml` pages are similar they will require a `<Slot />` tag. They will look like this.

    <!-- layout.phml -->

    <>
        {Your content here}
        <Slot />
        {Your content here}
    </>

    <!--       or       -->

    <{html-tag}>
        {Your content here}
        <Slot />
        {Your content here}
    </{html-tag}>

Markdown files are normal markdown files but you may also have frontmatter/metadata. The frontmatter should be written in yaml. This data is exposed to the layouts on page render.

    ---
    title: Sample Page Title
    pubDate: Thu, 23 May 2023 UTC
    tags:
        - sample
        - docs
        - getting_started

    ---

    # Sample Page

    Some content here

There are also components which are in the `src/components` directory by default. They are structure just like the `page.phml` file. After creating a component it's filename and path are used to create the associated element tag which can be used in any `page.phml` , `layout.phml` , markdown, and other component files. All sub directories leading to the component are used in the name and are separated with a `.` . So if you have a component file named `Sample.phml` you will get a `<Sample>` tag to use in all other files. If you have a component file `nav/Navbar.phml` you will get a `<Nav.Navbar />` tag to use in all other files. If you want to use the component like a normal element and not just a self closing element you can add a `<Slot />` element where you want all the children to be placed in the component. To see more on how components work, it is recommended to read up on the phml docs as phml's default component system is what is used here in Mophidian.

It may be easier to have more of an example. Suppose you have the file structure of

    src/
    ├ components/
    │ └ Sample.phml
    └ pages/
      ├ page.phml
      ├ layout.phml
      └ Sample.md

With the files containing

    <!-- Sample.phml -->

    <div>Component</div>

    <!-- layout.phml -->

    <>
        <h3>Header</h3>
        <Slot />
    </>

    <!-- page.phml -->

    <>
        <h1>Home</h1>
        <Sample />
    <>

    # Sample markdown page

    Page content

With each page inheriting from it's corresponding layout you get a built output that has the structure of

    out/
    ├ index.html
    └ Sample
      └ index.html

and file with the contents of

    <!-- out/index.html -->

    <!DOCTYPE html>
    <html>
        <head>
            ... <!-- See rendering section -->
        </head>
        <body>
            <h3>Header</h3>
            <h1>Home</h1>
            <div>Component</div>
        </body>
    </html>

    <!-- out/Sample/index.html -->

    <!DOCTYPE html>
    <html>
        <head>
            ... <!-- See rendering section -->
        </head>
        <body>
            <h3>Header</h3>
            <article>
                <h1>Sample markdown page</h1>
                <p>Page content</p>
            </article>
        </body>
    </html>

To view your changes in real time use `moph serve` and if you want to preview your changes you can use `moph preview` . To automatically open the website in a browser you may use the `-o|--open` flag.

To find out more about how the file structure works see the File System section.

## Building

To build you project you use `moph build` . This will incrementally build your site. This means if a rendered output of a page is the same as what was generated in the previous call of `moph build` , the page will be skipped. You may bypass this feature with the `--dirty` flag.

By default the built/rendered files will be output to the `out/` directory. These files are what you upload to your choice of site hosting.

## Summary

Use `moph new {project name}` to create a new project. Fill your newly creating project with `page.phml` , `layout.phml` , and markdown files. Then build your site with `moph build` .

To learn more about the in depth features of mophidian please read the rest of the documentation.