Standards and Conventions

Building Your App

Here is the standard breakdown of what your file should likely look like

---

# import Render Engine components
# import render_engine built-in parsers
# import render engine plugins and themes
from render_engine import Site, Page, Collection
from render_engine.parsers.markdown import MarkdownPageParser
from render_engine_kjaymiller_theme import kjaymiller
from render_engine_youtube_embed import YouTubeEmbed

# create Site() as `app` or `site`
# add your `output_path` (if not default)
# add local `static_paths`
# register plugins and themes

app = Site()
app.output_path = "output"
app.static_paths.add("static")
app.register_plugins(YouTubeEmbed)
app.register_theme(kjaymiller)

# add any custom settings
settings = {
   "SITE_TITLE": "My Cool Website",
   "SITE_URL": "http://example.com",
   "plugins": "YouTubeEmbed": {...},
   "theme": {...},
}
app.site_vars.update()

# Add Routes. Start with single pages and add Collections
@app.page
class Index(Page):
    ...

@app.collection
class Pages(Collection):
    ...

---

Site_Vars

Best Practices

PREFER UPDATE OVER OVERWRITING

When you provide your own settings, it's best to update instead of overwriting.

INSTEAD OF

site = Site()
settings = {
    "SITE_TITLE": "My Cool Site"
}
site.site_vars = settings

DO THIS

site = Site()
settings = {
    "SITE_TITLE": "My Cool Site"
}
site.site_vars.update(settings)

Default site_vars

site_vars: dict = {
    "SITE_TITLE": "Untitled Site",
    "SITE_URL": "http://localhost:8000/",
    "DATETIME_FORMAT": "%d %b %Y %H:%M %Z"
}

Commonly Used Site Vars

While you have any site variables passed into your Site, there are a lot of conventions that render-engine recommends so that it's easier for users to swap between themes.

For how to best add your settings, visit the Getting Started - Simple Site Layout and the site_vars best practices.

site_vars = {
    "NAVIGATION": [
        # Use a list of dictionary or objects that can be iterated through and accessed with
        # {% for link in NAVIGATION %}
        # <a href="{{link.url}}">{{link.text}}</a>
        {
            "text": "Home",
            "url": "/",
        },
        {
            "text": "Internal-Link",
            "url": "/link-to-site",
        {
            "text": External Links,
            "url": "https://full-url",
        }
   ],
   "SOCIAL": {
       # Social can hold information such as your username or url. We use the key:value and suggest a standard set of social naming
       "facebook": "username",
       "github": "@username",
       "linkedin": "handle" # The "xxxxx" in "http://linkedin.com/in/xxxxx"
       "tiktok": "@username",
       "x-twitter": "@username", # We're using "x-twitter" as using "X" could cause confusion
   }
}