Example of markdown functions:
Today's Date: Dec 22, 2024
Get Date 2023-04-30: April 30, 2023

Simple Render Base

This is a proof-of-concept for a simplified SEO renderer. This follows the paradigm originally created for the seo-directory-renderer but is optimized for different users. That targets software engineers and focuses on rigorous static analysis an the use of standard tooling to work within an engineer's workflow. This enabled fully-offline development, snapshot testing and inadvertent change detection, programmatic enforcement of the contract between the renderer and its backing data, automatic documentation of data structures, auto-formatting, standardized logging, enforcement of best practices, and build-time detection of possible error conditions. All these features came at the cost of complexity, which made the repo inaccessible to much of the SEO team.

The focus of this repo is to start fresh with a focus on accessibility over automated tooling. It is indented for use by SEO experts who may not be as familiar or comfortable with full-featured tooling intended for engineers. Our hypothesis is that by removing these barriers, experts in the domain of SEO will be able to contribute directly, review more meaningfully, and better correlate a change with its effect on the directory. This, of course, comes an added manual steps for data structure documentation, error scenario checking, code formatting, etc.

This will initially a base for additional simple renderers.

Contributing

This reposity is intended for development using GitHub Codespaces. Please see the quickstart for more info on how to get started.

The codespace configuration will default to a view that allows for editing, previewing, and sharing.

This repository follows the same basic development procedure used across our other apps and the industry at large. If you have never used git or GitHub before, start here and then work through the courses here.

Create a new feature branch in git.
Make, commit, and push the intended changes.
Open a pull request into the main branch.
Review and merge the pull request.

When a change is merged into main, automation will build a new version. Any infrastructure repository that uses this code (in this case only tcg-pubrec-services) will detect the new version and create a pull request on itself, allowing a final review before it's deployed to production.

Advanced

The codespaces configuration should be sufficient for most development, without any manual input. For local development outside of codespaces or for debugging purposes, this section may be useful.

This requires that node and npm are installed.

# Install project dependencies.
npm install

# Run a local development instance using wrangler.
npx wrangler dev --local 

    # or from package.json
    npm run dev

# Open the development preview server in a web browser.
open http://localhost:8787/

# NPM COMMANDS

# ESbuild Once, and Gulp Compile Once
npm run build

# Start gulp compiler
gulp
or
npm run gulp

# ADDITIONAL ENVIRONMENT VARIABLES SET IN TOML FILE, SUCH AS A LOCAL API
npm run local

Dynamic Routing

Located in the /src/routes.csv file there are two columns, the regex route and template/page_type to that route.

path,template
/,home
/articles(?:/(?<article>[_a-z]+))?(?:/(?<page>[\d]+))?/?,articles
/tables/(?<table>\w+)/?,tables

Routes can are strings that represent a regex string, if they contain groups (?<key>) then the value of the string in the group is the key in the data object and the value of the group is the key of the content that would be avaiable under the key in the data object. 🥁

Create Content

All content editable files are located in the `./src/` folder

create the content, then instantiate it.

/src
    > assets (less and jsrc)
    > markdown (.md files)
    > partials (repeatable html like head.html)
    > tables (.csv files)
    > templates (.html files for page_types)

Other than the assets folder, these directories have a index.js file in them. This is where you let the codebase know where you're newly created content is and that it can use it.

./src/markdown/index.js

import slug_of_md_article from "./articles/slug_of_md_article.md";

export default {
    slug_of_md_article
}

`/src/assets/` less(.less) and jsrc(.js) files are compliled and compressed with already running gulp file.

When npm run dev is ran, it kicks off the gulp compiler npx gulp

This watches all files within the /src/assets/jsrc and /src/assets/less directories, excluding seo.less and normalize.less
Sometimes it completely fails, do be afraid to ctl+c then npm run dev again.

YAML - Content Split

Template(templates/*.html) and Markdown(markdown/*.md) only have a feature where you can implement Data in the form of yaml syntax at the top of the file.

This data can be used in the context it is written, and bubbles up from Markdown files to Templates, to Partials.

Markdown is seperated by -----.md and Templates are seperated by -----<!DOCTYPE html>

example:

/src/markdown/articles/slug_of_md_article.md

...
title: Article Example
-----.md
# ARTICLE README
...

/src/templates/home.html

...
h1: Just A Landing Page To Get Started
-----
<!DOCTYPE html>
<html lang="en">
...

Mustache and Markdown

Mustache

JavaScript Mustache syntax is a simple templating language that allows developers to dynamically generate HTML content. It is named after the curly braces that resemble a mustache, which are used to denote variables that are to be replaced with actual values at runtime. Mustache syntax can be used in a variety of programming languages, including JavaScript, PHP, Ruby, and others.

The main benefit of Mustache syntax is its simplicity and ease of use. It is a lightweight language that does not require any special tools or libraries to work with. However, its simplicity can also be a pitfall, as it lacks some of the more advanced features of other templating languages, such as advance logic and methods. Although condition of existance and loops are allowed.

<html lang="en">
    <head>
        { {> HEAD} }
    </head>
    <body>
        { {> HEADER } }

        <main>
            <h1>
                { { h1 } }
            </h1>

Transforms into:

<html lang="en">
    <head>
        <meta name="namespace" content="strings and stuff" />
    </head>
    <body>
        <nav>
            <a href="/">home</a>
        </nav>

        <main>
            <h1>
                This is actual value of a H1
            </h1>

Markdown

Markdown syntax, on the other hand, is a lightweight markup language used for formatting plain text. It is designed to be easy to read and write, and is used widely for creating documentation, blog posts, and other types of content. Markdown syntax uses special characters to denote formatting, such as * for bold text and # for headings.

The main benefit of Markdown syntax is its simplicity and ease of use. It allows writers to focus on the content of their writing without getting bogged down in formatting details. However, like Mustache syntax, its simplicity can also be a pitfall, as it lacks some of the more advanced formatting options of other markup languages, such as tables and footnotes.

    # This is an h1
    - this is list item one
    - this is list item two

Transforms into:

    <h1>This is an h1</h1>
    <ul>
        <li>
            this is list item one
        </li>
        <li>
            this is list item two
        </li>
    </ul>

In Summary

While Mustache and Markdown syntax are used for different purposes, they can work together to create dynamic and formatted content. For example, a developer could use Mustache syntax to generate HTML content from data stored in a database, and then use Markdown syntax to format that content for display on a website.

Go to tables markdown file and route to see an example!

### Table Data from MarkDown
{ {#alltables.lorem.length} }
{ {#alltables.lorem} }  
* ***ID:*** { {ID} }
* ***Name:*** { {Name} }
* ***Email:*** { {Email} }
* ***Phone:*** { {Phone} }
* ***Country:*** { {Country} }
---  
{ {/alltables.lorem} }  
{ {/alltables.lorem.length} }

The main difference between Mustache and Markdown syntax is their purpose and scope. Mustache syntax is designed for generating dynamic content, while Markdown syntax is designed for formatting plain text. Both are simple and easy to use, but they serve different needs and are best used in their respective contexts.

* I have to put a space within the curly brackets so this specific markdown file doesn't render it as data points 😊