From 01a7c3904994901a1cf4b491eb5414576c4c2005 Mon Sep 17 00:00:00 2001 From: sanderelias Date: Sat, 4 Jul 2020 08:43:08 +0200 Subject: [PATCH 1/6] docs(scully): add FAQ document to docs --- docs/faq.md | 98 ++++++++++++++++++++++++++++++++++++++++ libs/ng-lib/package.json | 2 +- libs/scully/package.json | 2 +- 3 files changed, 100 insertions(+), 2 deletions(-) create mode 100644 docs/faq.md diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 000000000..d3e520d91 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,98 @@ +--- +title: Frequently Asked Questions +order: 9000 +lang: en +--- + +# Frequently Asked Questions + +
+ + language in route? + + +> In my project i have a routing like this:
+> /:lang
+> /:lang/page1
+> /:lang/page2
+> etc...
+> +> It's very simple. :lang can have few values (it, en...) and If possible I prefer to store it in the config, without have +> an endpoint dedicated.
How can I solve this? + +As the Scully config file is typescript, you can post-process the routing object. a very crude solution would be something like this: + +```typescript +import { ScullyConfig } from '@scullyio/scully'; + +const preLangConfig: ScullyConfig = { + /** settngs */ + routes: { + ':lang/route1': { type: 'default' }, + ':lang/route2': { type: 'default' }, + ':lang/route3': { type: 'default' }, + ':lang/route4': { type: 'default' }, + }, +}; +export const config = { + ...preLangConfig, + routes: Object.fromEntries( + // make sure you use a node-version that supports this, or use a reduce. + Object.entries(preLangConfig.routes).reduce((all, [route, config]) => { + if (route.includes(':lang')) { + ['it', 'en', 'nl', 'sp'].forEach(( + lang // <-- language array + ) => all.push([route.split(':lang').join(lang), config])); + } else { + all.push([route, config]); + } + return all; + }, []) + ), +}; + +console.log(config.routes); +``` + +It takes the `preLangConfig` and iterates over all the routes. When it finds the `:lang` parameter, it creates an entry with every value provided in the language array. That way the final config will have a route for every language available. + +
+ +
+Ignore routes without config? +> In my app I have a lot of routes I don't want scully to handle. How can I deal with that. + +Scully will use the `default` plugin for any route that is not specified. When you want to have another way to handle defaults, you can replace this plugin with another one. +For example, if you want to ignore all undefined routes you can do: + +```typescript +registerPlugin('router', 'default', findPlugin('ignored')); +``` + +In case you want to have some more control, you can create a custom plugin: + +```typescript +registerPlugin( + 'router', + 'default', + async (route: string): Promise => { + if (route === 'somethingSpecial') { + return [{ route, type: 'somethingElse' }]; + } + if (route === 'somethingSpecial/:id') { + const data = httpGetJson('someEndPoint'); // fetch some json + const { createPath } = routeSplit(route); + const routes: HandledRoutes[] = []; + for (const row of data) { + routes.push({ route: createPath(row.id), type: 'default' }); + } + return routes; + } + return []; + }, + undefined, + { replaceExistingPlugin: true } +); +``` + +
diff --git a/libs/ng-lib/package.json b/libs/ng-lib/package.json index f2013117f..7b40905be 100644 --- a/libs/ng-lib/package.json +++ b/libs/ng-lib/package.json @@ -1,6 +1,6 @@ { "name": "@scullyio/ng-lib", - "version": "0.0.24", + "version": "0.0.25", "repository": { "type": "GIT", "url": "https://github.com/scullyio/scully/tree/main/projects/scullyio/ng-lib" diff --git a/libs/scully/package.json b/libs/scully/package.json index dd2299e46..67eed413b 100644 --- a/libs/scully/package.json +++ b/libs/scully/package.json @@ -1,6 +1,6 @@ { "name": "@scullyio/scully", - "version": "0.0.98", + "version": "0.0.99", "description": "Scully CLI", "repository": { "type": "GIT", From 2042a86c8c6ceff3dd46fbc373478f6b206ad6c2 Mon Sep 17 00:00:00 2001 From: sanderelias Date: Sat, 4 Jul 2020 08:45:41 +0200 Subject: [PATCH 2/6] test(docsWeb): update snapshots --- .../__snapshots__/docsThere.spec.ts.snap | 168 +++++++++++++++--- 1 file changed, 141 insertions(+), 27 deletions(-) diff --git a/tests/jest/src/__tests__/__snapshots__/docsThere.spec.ts.snap b/tests/jest/src/__tests__/__snapshots__/docsThere.spec.ts.snap index 6a43e58a2..65ab38e77 100644 --- a/tests/jest/src/__tests__/__snapshots__/docsThere.spec.ts.snap +++ b/tests/jest/src/__tests__/__snapshots__/docsThere.spec.ts.snap @@ -30,7 +30,7 @@ exports[`docsSite should have content for all markdown files check html for mark - \\"scullyLogo\\"

Code of Conduct

+ \\"scullyLogo\\"

Code of Conduct

As contributors and maintainers of the Scully project, we pledge to respect everyone who contributes by posting issues, updating documentation, submitting pull requests, providing feedback in comments, and any other activities.

Communication through any of Scully's channels (GitHub, Gitter, Twitter, etc.) must be constructive and never resort to personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.

We promise to extend courtesy and respect to everyone involved in this project regardless of gender, gender identity, sexual orientation, disability, age, race, ethnicity, religion, or level of experience. We expect anyone contributing to the Scully project to do the same.

@@ -72,7 +72,7 @@ exports[`docsSite should have content for all markdown files check html for mark - \\"scullyLogo\\"

Código de Conducta

+ \\"scullyLogo\\"

Código de Conducta

Como contribuyentes y mantenedores del proyecto Scully, nos comprometemos a respetar a todos los que contribuyen mediante la publicación de problemas, la actualización de la documentación, el envío de solicitudes de extracción, la retroalimentación en los comentarios y cualquier otra actividad. La comunicación a través de cualquiera de los canales de Scully (GitHub, Gitter, Twitter, etc.) debe ser constructiva y nunca recurrir a ataques personales, trolling, acoso público o privado, insultos u otra conducta no profesional. Prometemos extender la cortesía y el respeto a todos los involucrados en este proyecto, independientemente de su género, identidad de género, orientación sexual, discapacidad, edad, raza, etnia, religión o nivel de experiencia. Esperamos que cualquiera que contribuya al proyecto Scully haga lo mismo. @@ -114,7 +114,7 @@ exports[`docsSite should have content for all markdown files check html for mark - \\"scullyLogo\\"

Introduction (Alpha)

+ \\"scullyLogo\\"

Introduction (Alpha)

What is Scully?

Scully is the best static site generator for Angular projects looking to embrace the JAMStack.

How does it work?

@@ -177,7 +177,7 @@ exports[`docsSite should have content for all markdown files check html for mark - \\"scullyLogo\\"

Creating a Blog

+ \\"scullyLogo\\"

Creating a Blog

Scully is the best option for moving a blog to Angular! It provides a schematic that enables Angular applications to use markdown files for blog's content.

This guide covers the following topics:

    @@ -395,7 +395,7 @@ exports[`docsSite should have content for all markdown files check html for mark - \\"scullyLogo\\"

    Crear un blog

    + \\"scullyLogo\\"

    Crear un blog

    Scully es la mejor opción para mover tu blog a Angular!

    Tiene un schematic que permite que las aplicaciones de Angular utilicen archivos de markdown para el contenido del blog.

      @@ -500,6 +500,120 @@ CREATE mdblog/2020-03-24-blog.md (95 bytes) " `; +exports[`docsSite should have content for all markdown files check html for markdown docs/faq 1`] = ` +" + + ScullyDocs + + + + + + + + + \\"scullyLogo\\"

      Frequently Asked Questions

      +
      + + language in route? + + +
      +

      In my project i have a routing like this:
      +/:lang
      +/:lang/page1
      +/:lang/page2
      +etc...

      +

      It's very simple. :lang can have few values (it, en...) and If possible I prefer to store it in the config, without have +an endpoint dedicated.
      How can I solve this?

      +
      +

      As the Scully config file is typescript, you can post-process the routing object. a very crude solution would be something like this:

      +
      import { ScullyConfig } from '@scullyio/scully';
+
+const preLangConfig: ScullyConfig = {
+  /** settngs */
+  routes: {
+    ':lang/route1': { type: 'default' },
+    ':lang/route2': { type: 'default' },
+    ':lang/route3': { type: 'default' },
+    ':lang/route4': { type: 'default' },
+  },
+};
+export const config = {
+  ...preLangConfig,
+  routes: Object.fromEntries(
+    // make sure you use a node-version that supports this, or use a reduce.
+    Object.entries(preLangConfig.routes).reduce((all, [route, config]) => {
+      if (route.includes(':lang')) {
+        ['it', 'en', 'nl', 'sp'].forEach((
+          lang // <-- language array
+        ) => all.push([route.split(':lang').join(lang), config]));
+      } else {
+        all.push([route, config]);
+      }
+      return all;
+    }, [])
+  ),
+};
+
+console.log(config.routes);
      +

      It takes the preLangConfig and iterates over all the routes. When it finds the :lang parameter, it creates an entry with every value provided in the language array. That way the final config will have a route for every language available.

      +
      + +
      +Ignore routes without config? +> In my app I have a lot of routes I don't want scully to handle. How can I deal with that. + +

      Scully will use the default plugin for any route that is not specified. When you want to have another way to handle defaults, you can replace this plugin with another one. +For example, if you want to ignore all undefined routes you can do:

      +
      registerPlugin('router', 'default', findPlugin('ignored'));
      +

      In case you want to have some more control, you can create a custom plugin:

      +
      registerPlugin(
+  'router',
+  'default',
+  async (route: string): Promise<HandledRoute[]> => {
+    if (route === 'somethingSpecial') {
+      return [{ route, type: 'somethingElse' }];
+    }
+    if (route === 'somethingSpecial/:id') {
+      const data = httpGetJson('someEndPoint'); // fetch some json
+      const { createPath } = routeSplit(route);
+      const routes: HandledRoutes[] = [];
+      for (const row of data) {
+        routes.push({ route: createPath(row.id), type: 'default' });
+      }
+      return routes;
+    }
+    return [];
+  },
+  undefined,
+  { replaceExistingPlugin: true }
+);
      +
      +
       + + +" +`; + exports[`docsSite should have content for all markdown files check html for markdown docs/features 1`] = ` " @@ -530,7 +644,7 @@ exports[`docsSite should have content for all markdown files check html for mark - \\"scullyLogo\\"

      Scully's Features

      + \\"scullyLogo\\"

      Scully's Features

      Under the hood, Scully analyzes an Angular application and generates a static version of it. It provides several Angular schematics to make its usage AS EASY AS POSSIBLE!

      @@ -594,7 +708,7 @@ exports[`docsSite should have content for all markdown files check html for mark - \\"scullyLogo\\"

      Caracteristicas de Scully

      + \\"scullyLogo\\"

      Caracteristicas de Scully

      Tras bambalinas, Scully analiza la aplicación de Angular y genera una versión estática de esta. Proporciona varios esquemas (schematics) de Angular para hacer su uso LO MÁS SENCILLO POSIBLE!

      Características Principales:

      @@ -657,7 +771,7 @@ exports[`docsSite should have content for all markdown files check html for mark - \\"scullyLogo\\"

      Getting Started with Scully

      + \\"scullyLogo\\"

      Getting Started with Scully

      Welcome to Scully!

      Before getting started, please read the Prerequisites.

      All about Scully in one video : Building the Fastest Angular Apps Possible

      @@ -760,7 +874,7 @@ exports[`docsSite should have content for all markdown files check html for mark - \\"scullyLogo\\"

      Iniciando con Scully

      + \\"scullyLogo\\"

      Iniciando con Scully

      ¡Bienvenido a Scully!

      Antes de iniciar, por favor lea los Prerrequisitos.

      Todo acerca de Scully en un video : Construyendo las Apps de Angular más rápidas

      @@ -889,7 +1003,7 @@ exports[`docsSite should have content for all markdown files check html for mark - \\"scullyLogo\\"

      Introducción (Alfa)

      + \\"scullyLogo\\"

      Introducción (Alfa)

      ¿Qué es Scully?

      Scully el mejor generador de sitios estáticos para proyectos de Angular buscando adoptar JAMStack.

      ¿Cómo funciona?

      @@ -952,7 +1066,7 @@ exports[`docsSite should have content for all markdown files check html for mark - \\"scullyLogo\\"

      Issues

      + \\"scullyLogo\\"

      Issues

      To create a bug report: Go to Scully Bug template.

      To propose a new feature: Go to Scully Feature request

      The Scully team is working on better documentation for creating issues.

      @@ -992,7 +1106,7 @@ exports[`docsSite should have content for all markdown files check html for mark - \\"scullyLogo\\"

      Plugins

      + \\"scullyLogo\\"

      Plugins

      Scully uses a plugin system that allows users to define new ways for Scully to pre-render an application. There are five main types of plugins:

        @@ -1290,7 +1404,7 @@ exports[`docsSite should have content for all markdown files check html for mark - \\"scullyLogo\\"

        Plugins

        + \\"scullyLogo\\"

        Plugins

        Scully utiliza un sistema de plugins que permite a los usuarios definir nuevas formas en las que Scully haga el pre-render de la aplicación. Hay cinco tipos principales de plugins:

          @@ -1588,7 +1702,7 @@ exports[`docsSite should have content for all markdown files check html for mark - \\"scullyLogo\\"

          Polyfills

          + \\"scullyLogo\\"

          Polyfills

          Depending on the browser and environment that the application targets, some polyfills are required. This page lists the recommended polyfills.

          Event() constructor

          @@ -1634,7 +1748,7 @@ exports[`docsSite should have content for all markdown files check html for mark - \\"scullyLogo\\"

          Prerequisites

          + \\"scullyLogo\\"

          Prerequisites

          You need an existing Angular application, or you can create a new one in order to use Scully.

          NOTE: Scully supports Angular versions: v8.x.x and v9.x.x

          Creating a New Angular Application

          @@ -1689,7 +1803,7 @@ exports[`docsSite should have content for all markdown files check html for mark - \\"scullyLogo\\"

          Requisitos Previos

          + \\"scullyLogo\\"

          Requisitos Previos

          Necesita una aplicación existente de Angular o puede crear una nueva para usar Scully.

          NOTA: Scully soporta las versiones: v8.x.x y v9.x.x de Angular.

          Crear Una Nueva Applicación de Angular

          @@ -1744,7 +1858,7 @@ exports[`docsSite should have content for all markdown files check html for mark - \\"scullyLogo\\"

          Recommended Plugins

          + \\"scullyLogo\\"

          Recommended Plugins

          If you would like to add a plugin to this list; edit the docs/recommended-plugins.md file and submit a PR.

          Scully Official Plugins