novaconium/novaconium/pages/admin/docs/getting-started/index.twig

{% extends 'admin/docs/_layout/layout.twig' %}

{% block title %}Getting started{% endblock %}

{% block description %}Requirements, running locally, and deploying on Apache.{% endblock %}

{% block robots %}noindex, nofollow{% endblock %}

{% block docs_content %}
    <h1>Getting started</h1>

    <p><strong>Requirements:</strong> PHP 8.1+ (uses <code>readonly</code> constructor-promoted properties) and, for production, Apache with <code>mod_rewrite</code> and <code>AllowOverride All</code>. The <a href="/admin/docs/database">Database</a>/<a href="/admin/docs/content-index">Content index</a> features are optional and off by default — see <a href="/admin/docs">Overview</a> for the extensions they need (<code>pdo_sqlite</code>, optionally <code>pdo_mysql</code>/FTS5) if you turn them on.</p>

    <h2>Run it locally (no Apache needed)</h2>

    <pre><code>php -S 127.0.0.1:8000 -t public public/router.php</code></pre>

    <p><code>public/router.php</code> is a dev-only script that mimics the <code>.htaccess</code> rules (canonical redirects + static cache lookup) so you can develop without Apache. It is never used in production — Apache reads <code>public/.htaccess</code> directly.</p>

    <p>Visit:</p>
    <ul>
        <li><code>http://127.0.0.1:8000/</code> — static home page</li>
    </ul>

    <h2>Deploy on Apache</h2>

    <p>Point the vhost's document root at <code>public/</code>, make sure <code>mod_rewrite</code> is enabled and <code>AllowOverride All</code> is set for that directory so <code>public/.htaccess</code> takes effect, and it just works — no build step required.</p>

    <h2>Starting a new project</h2>

    <p>Clone this repo and drop its Git history — that's it, there's no Composer scaffold or installer:</p>

    <pre><code>git clone --depth 1 &lt;novaconium-repo-url&gt; my-new-project
cd my-new-project
rm -rf .git
git init
git add -A
git commit -m "Initial commit from novaconium template"</code></pre>

    <p>Then replace the example content that ships under <code>App/pages/</code> (the <code>about</code>/<code>blog</code>/<code>contact</code> sample pages) with your own pages, lib classes, and config. Leave <code>novaconium/</code> and <code>public/</code> as-is.</p>

    <h2>Updating the framework</h2>

    <p>Because the framework core lives entirely under <code>novaconium/</code> — separate from your project's <code>App/</code> — picking up a new release is a matter of overwriting that one directory and committing the diff:</p>

    <pre><code>git clone --depth 1 --branch &lt;release-tag&gt; &lt;novaconium-repo-url&gt; /tmp/nova-update
rm -rf novaconium
cp -r /tmp/nova-update/novaconium ./novaconium
rm -rf /tmp/nova-update
git add novaconium
git commit -m "Update novaconium framework to &lt;release-tag&gt;"</code></pre>

    <p>This is safe by construction: the override-by-path design means <code>App/</code> always wins over <code>novaconium/</code> for pages, lib classes, and Sass colors (see <a href="/admin/docs/project-layout">Project layout</a>), so an update can't clobber your project's customizations. Diff before committing to see what changed, and run <code>php novaconium/bin/clear-cache.php</code> afterward since a framework update can change rendered output.</p>

    <h2>Adding a new page</h2>

    <p>Create a directory under <code>App/pages/</code> with an <code>index.twig</code> — the directory path <em>is</em> the URL (see <a href="/admin/docs/routing">Routing</a>). <a href="/admin/docs/seo">SEO</a> has a ready-to-paste starter template with every overridable block (title, description, Open Graph, Twitter Card) plus a content stub — copy it in and fill in the blanks.</p>

    <p>Or skip the copy-paste entirely:</p>

    <pre><code>php novaconium/bin/create-static-page.php blog/my-new-post</code></pre>

    <p>Scaffolds <code>App/pages/blog/my-new-post/index.twig</code> from that same starter template, with the title pre-filled from the last path segment ("my-new-post" → "My New Post"). The path can be given with or without a trailing <code>.twig</code> or <code>/index.twig</code> — refuses to run if the page already exists, or if any segment is reserved (starts with <code>_</code>, or is literally <code>404</code> — see <a href="/admin/docs/routing">Routing</a>).</p>
{% endblock %}