The Developer Kitchen Sink - adobecom/milo GitHub Wiki

The following is a list of resources to help you with your journey learning Franklin and Milo.

Questions

If you have questions, ask them here: https://milo.adobe.com/community

If you have a question and don't know where to ask (or is private), use: https://git.corp.adobe.com/orgs/wcms/discussions

Remember: share early and share often.

Franklin overview / architecture

https://github.com/adobe/helix-home/blob/main/docs/architecture.md#aws-delivery-stack

Above you will find the Franklin architecture diagram.

In short, Franklin takes documents created in Word or Google Docs and converts them to markdown (.md). These files live in an object store (S3). For code (JS & CSS), files pushed to Github will be automatically copied to another object store. When a request happens, JS & CSS are delivered straight off the object store and the MD is converted to HTML at time of request.

Note: there is no server-side extensibility in Franklin. All functionality should be done client-side or a 3rd party service (I/O Runtime).

Prerequisites

Knowledge

It is highly encouraged a developer has a basic understanding of HTML, CSS, and JS. A deep understanding of ES6 is strongly encouraged.

Software

  1. Node v16+
  2. NPM 8+

Servers vs Serverless

Franklin sits on a serverless architecture. This means you do not "provision" anything to get up and running. The URLs you use for Franklin can be tied back to your project's github information:

https://{branch-name}--{repo-name}--{repo-owner}.hlx.page

What comes OOTB with Franklin

  1. DOCX to MD to HTML
  2. Viewing HTML without the head tag (*.plain.html)
  3. XLSX to JSON
  4. Creating indexes of content (query-index.yaml / query-index.json)
  5. Creating sitemaps from content indexes (helix-sitemap.yaml)
  6. Handle form submissions
  7. Handle previewing and publishing content
  8. Ability to upload PDF and SVG

What is Milo vs Franklin

Franklin is a CMS application. You can think of Milo as a Franklin SDK for creating sites for Franklin. Milo comes with features to extend Franklin capabilities to make building sites for adobe.com easier.

When a Milo-based project is created, it will use Milo as a central place for many common features. Including:

  1. Blocks (aka components)
  2. Localization
  3. Authoring enhancements - library, tools, etc.
  4. Globalization (GeoRouting)
  5. General purpose utilities (SVGs, icons, placeholders, link decorators, etc.)

Getting started developing on Franklin & Milo

Entry-level developer brown bag

Milo developer brown bag (skip to 24:05)

Performance

Milo Performance Brown Bag - A deep dive into Milo's performance life cycle.

Testing Milo

Testing on Milo

Unit test best practices

Building a Milo-based project from scratch

Build a milo-project from scratch

Covers creating a new repo, setting up content, tying code and content together, and handling permissions for content. A few extras as well.. anatomy of a consuming project, debugging, relationship between milo and consumers, etc.

Code & Content

Some pieces of content and code must live in specific places in order for them to work. The following provides some guidance on these pieces.

Content Root

The content root is where you content should live. This can be / or it can be something like /acrobat (www.adobe.com/acrobat) this is to help many projects share the same domain.

Code Root

Setting the code root can also help to avoid JS & CSS collisions when multiple projects share the same domain:

  1. www.adobe.com/acrobat/scripts/scripts.js
  2. www.adobe.com/express/scripts/scripts.js
  3. etc.

Files required at base

There are certain files that cannot live in your codeRoot or contentRoot paths. Some of these files will live in github, and some will live in SharePoint.

GitHub Repository

  1. head.html
  2. fstab.yaml
  3. helix-query.yaml
  4. helix-sitemap.yaml
  5. .hlxignore
  6. helix-version.txt

SharePoint Folder

  1. .helix
    1. config.xlsx - Used to set cache flushing credentials
    2. headers.xlsx - Used to set headers for the entire site
  2. metadata.xlsx - Used to set shared metadata properties across the site (much like Inherited Page Properties in AEM)
  3. redirects.xlsx - Used for redirects

Content Mapping Examples

Content mapping video

Block Library

Library Docs

Naming conventions

We try to make names as human readable as possible. While true or false can be developer friendly, they are not human friendly. Instead of {true|false} we prefer {on|off}.

It's also best to not put boolean-like values as part of query parameters as they are harder to remember:

// good
?martech=off

// bad
?disableMartech=on

When architecting a solution where a human is involved, please try to keep this guidance in mind.

WIP Below

  1. Git workflow and playing/previewing with branches with Milo / Franklin
  2. Milo Blocks and how can u create a new one
  3. Authoring
  4. Metadata
  5. Running Milo locally with HTTPS
  6. PR and Checks
  7. Milo Release Workflow
  8. How / Why you must care about performance of your code (as opposed to how it was writing server side code in AEM)
  9. Unit testing
  10. Working / debugging out of your local environment
  11. Localization overview
  12. Using Adobe I/O
  13. Workflow equivalent in Franklin / Milo
  14. Permissioning model in Franklin / Milo

Milo Training Videos

Session 1 : Franklin/Milo Principles

Session 2 : Milo Authoring refinement

Session 3 : Milo Working processes

Session 4 : Milo Performance