Documentation 2.0 Structure

After gathering feedback and working on the mindmap for Frontity’s knowledge here you have the Documentation Structure 2.0 proposal we have for the new structure of documentation sites

There will be 3 “documentation” sites:

  • Documentation Site (available at docs.frontity.org)
  • API Reference Site (under development, to be on the ‘api’ subdomain)
  • Step by Step guide Site (under development, to be on the ‘tutorial’ subdomain)

Here you have the proposal of the documentation structure for the Documentation site that is based on the following Frontity Knowledge RoadMap MindMap

Feel free to share your feedback as we’ll begin to apply these changes soon in our documentation site

You also have available the structure of the API reference site although there are no big differences compared to those same section in the current documentation site


Documentation 2.0 Structure

Docs → docs.frontity.org

  • 0- Welcome to Frontity
    Index to resources in docs
    Highlight (with banners or similar) those resources we want

    • Banner → Step by Step
  • 1- Quick Start

  • 2- Understanding Frontity

    • What is Frontity?

      • Describe Frontity from different points of view
        • An alternative rendering engine for WordPress
        • A React framework to create WordPress themes
        • An Open Source Project
    • Why Frontity?

      Why Frontity from a Marketing/Product point of view. This diagram may be useful here

      • Features & Benefits
      • Comparisons
    • Foundational Concepts

      Technical ideas that makes possible the features. This sections is not supposed to explain in detail each idea but point out and remark those technical ideas that makes Frontity different like:

      • logic is delegated in packages
      • packages are organized through namespaces
      • Frontity creates a final app as the sum of packages used
      • Frontity uses 4 core elements to orchestrate packages:
        state, actions, roots & libraries
    • Frontity Modes

      Overview of the ways Frontity can be used (Decoupled Mode, Embedded mode, Serverles,… )

    • Browser Support

  • 3- A Frontity project
    These are the first things a developer will face in its Frontity project
    This section should cover topics recurrently asked from the community

    • Anatomy of a Frontity Project
      • Files Structure & Settings
      • Packages & Themes
        • Essential Packages: theme, source, router
    • Settings
      • frontity.settings.js
    • Styling
      • Styles with CSS-in-JS
      • Standard Styling with Global CSS Files
      • CSS Libraries and Frameworks
    • Flow of data
      • setting REST API
      • data: links info
      • entities
      • Normalization of data: Why
    • Development Stages
      • Development
      • Production
        • The Build Process
  • 4- Core Concepts

    • Frontity Core
      • State
      • Actions
      • Roots
      • Libraries
    • Packages
      • Namespaces
      • Essential Packages: theme, source, router
      • Other built-in packages: html2react, components, hooks
      • Third party NPM packages
      • NPM packages vs NPM Frontity packages
  • 5- Server Side Rendering

    • Isomorphic Apps
      • state.frontity.platform
      • Build → entry points
    • Lifecycle Actions
      • beforeSSR
      • afterSSR
  • 6- Architecture

    • Choosing between Decoupled or Embedded mode
      • Decoupled
      • Embedded
    • Serverless
    • MIddleware
      • Server Extensibility
  • 7- Deployment

    How to deploy a Frontity project

    • Vercel
    • Heroku
    • AWS
    • Netlify
  • 8- SEO

    • SEO on SSR
    • Metadata
      • Headers
      • YOAST
    • robots.txt
    • sitemaps.xml
  • 9- Performance

    • Cache
      • stale-while-revalidate
      • Cache REST API
    • Tools
      • Lighthouse
    • Minimal Bundle
    • Recommendations
      • Fonts
      • Code Splitting
    • Global CSS
  • 10- WordPress

    • How to work with CPT
    • Working with Gutenberg Blocks in a Frontity project
      • Applying html2react processors
  • 11- Guides

    Find some quick guides oriented on how to build things with Frontity

    This will evolve into a guides page, where guides will be able to be found through tags and search

    • TypeScript Guide

    • How to work with Slot and Fills

    • Understanding Mars Theme

    • Keep Frontity Updated

    • How to work with packages

      • Install a new Frontity package
      • Creating a Functional Package
    • How to work with handlers

    • How to share your Frontity Project

    • Troubleshooting guide

    • Setting your development environment

    • Accesibility Guide

    • Comparison guides

      There are some decission making docs that we should offer somewhere. Until we don’t have a better place we can start offering this content as Blog Posts or as Docs Guides

      This should cover the advantages of using Headless, and React over a traditional WP installation

      How does Frontity compare with other similar solutions?

      Why React? (reactivity…)

      • Frontity vs React
      • Frontity vs NextJS
  • 12- Contributing

    Explain more in detail that Frontity is an Open Source and how users can contribute
    Specific details about code contribution should be provided in the main repository (design principles, workflow, testing…)

    • How to contribute?
    • Contributing Guide
    • Design Principles
  • FAQ ??
    Not sure about having this section or the questions that should contain.

API Reference → api.frontity.org

This content in this site is meant to be used as a reference so detailed explanations will be provided

1 Like

Hey, great work guys!! I think these structure is much more clear then the one we currently have :clap:

I don’t have much else to add right now. I am sure more ideas and feedback will come up at a later stage for each of the sections, but this new structure makes a lot of sense to me as it is.

By the way, I guess you can reuse a lot of the content that Reyes is creating for the white paper for some of the sections that explain Frontity :slightly_smiling_face:

Hi @juanma.
Great job !
So far, I used docs.frontity.org combined with youtube channel to improve my skills. But now with the forthcoming tutorial site that will be easier for me.
I’m eager to read it.
Thanks :wink:

3 Likes

This looks great. :slight_smile:

I have a few questions (just out of curiosity):

  • As per this structure, where the Frontity Themes + Third Party Themes section would be? In Number 4 - Packages?
  • Is there going to be a section, area or page to collect learning resources from the community (tutorials, videos, talks, etc)?

They will be in the API Reference site → api.frontity.org under the Themes section

Yes, that content can be included as another section called Resources

1 Like

I think this is great @juanma :clap:

I’d just like to mention a couple things that I’d like to see us have in the new docs (This is mostly applicable to the API docs):

  • Switching between documentation versions (so that the docs for frontity [email protected] for example include don’t include the features that were added in the [email protected])

  • Include an “Added in [frontity version]” for specific APIs and maybe even have a “History” table for a particular API like in node.js docs.

    This makes is easier to understand when some feature was made available and if a user needs to upgrade in order to use it (if they are on an older version of frontity).

Hey @juanma thanks for putting this together. And sorry for my late answer.

Great Job, I love the new structure, and I think that it’s going to make things much easier.

I don’t have any suggestion that requires a major change on your proposal.


Great question Reyes.

I see that under the 3. A Frontity project > Anatomy of a Frontity Project section, there’s going to be an explanation of the Packages and Themes. Not sure if that’s going to be enough. My suggestion is that we create a whole section like Performance and SEO but for Themes and Extensions. The main reason is that we should explain how to use and how to create themes and extensions for Frontity, and that’s not going to be covered in the API site.


Other small things I’ve noticed:

  • To me, it looks like the section 10- WordPress could just be part of the 11- Guides section. As it looks like it’s only going to contain a couple of guides on how to do some things on WordPress.

  • Does it make sense to move the Frontity Modes section from 2- Understanding Frontity to 7-Deployment? Or maybe give a first explanation in the Understanding Frontity section, and afterwards explaining the technical details on how to handle the different architectures in the 7- Deployment section?

  • I think that the 7- Deployment section needs to cover also all the things related to WordPress instance. Specially the complications derived from the “Decoupled architecture” (What theme should I use? How do I handle redirections?..)

@Pablo @mmczaplinski Thanks for your feedback and suggestions!

I don’t see how can we implement this with the current platform we have as gitbook only allows creating these variants per site and not per section, and as we’ll different packages documented under api.frontity.org I think this cannot be done with the current platform

Besides this, I’d also like being able to have this in the docs. So we’ll take into account when we look for another platform for the docs in the next quarters

Yes, this is something that I think we can start doing. It will require more effort when creating documentation but I think it will be very useful for the community.

I think you’re right. This topic is important enough to have its own section :+1:

We consider there will be more info to be documented related to WordPress that will be easier to locate on its own section.

Some of the sections can be considered as a group of guides for a specific topic, but until we don’t have a proper guides site where each guide can be tagged, searched and easily located, we think it’s best to group these related info (guides and more) in specific sections that we consider will be frequently looked for.

Yes, that’'s exactly the approach, Provide an introduction (an overview) in Understanding Frontity and then provide the details later, but in this case the details will be provided in the Architecture section (and not in the Deployments section)

This info could be in the WordPress section and reference them from any Architecture or Deployment explanations

1 Like

That is a great idea. Actually, maybe we should start doing so in our TSDocs as well so it is easier to add it to the docs. Which, by the way, WordPress does it with the @since tag. It is not going to be that easy but we can talk about it.

To not hijack this thread, I will add it to the Code <-> Documentation workflow one :slightly_smiling_face:. Please answer there.

@pablo Regarding this, I think the right place to explain this is Core Concepts > Packages
I’ve added this idea of explaining “how to use and how to create themes and extensions for Frontity” there

Great, It makes sense to have them under “Core concepts” as well :slight_smile:

Also happy to read your replies to all my previous feedback, it looks like you had everything in mind already!

1 Like