This August I will be participating as a trainer at a major Angular conference, https://ngconf.co/. I am super excited about it and was already putting the lessons together to spread all the knowledge I can on Angular Schematics, to fellow developers.
It is going to be a peculiar workshop, due to COVID-19, since I can't be present and it must be all online. I was thinking about how to make the best of it and occurred to me that having the lessons neatly documented, was the best option.
And now I can have it! So I did.
I could potentially have a regular, dynamic Angular app, why not? But when it comes to documentation...do I really need it?
The answer is probably not! However, I do have a few requirements.
- I want to be able to paste code snippets, or embed github gists
- I want to have a dynamic navigation that updates itself automatically, as opposed to manually
- I want to easily create every new content page out of markdown
- I want to have continuous deploys and integration of new content, even on an automated or programmed basis
In case you did not know it, ever since December 2019. Angular has its own, dedicated Static Sites Generator, Scully.io. If you don't know why Static Site Generation is good for you and the performance of your site, watch this video. I explain there the many rendering strategies, and the pros and cons.
You can easily install Scully with schematics/CLI in any Angular application, by running
$ ng add @scullyio/init
There you go!
Hold on, you need to make sure you have Angular and CLI on at least version 8, and that you are running a version of node, higher than 10.
Your application needs to be router enabled, of course, because ** Scully maps your routes to regular paths **
Now---yes, there you go!
The next thing we will do is creating a new module called
$ ng generate module docs --route=docs --module=app-routing
Now we will go to the docs.component.html template, and make sure to add the mandatory Scully injection tag
We will also create an additional component called
sidenav, to maintain our dynamic side navigation
Once you have generated this component, we will use the
ScullyRoutesService to keep a list of all our documents. It should look like this, where we leverage the
$available published routes.
This service basically reads the
/src/assets/scully-routes.json generated by Scully while generating your HTML pages.
Now you only have to create an ordered list to keep your docs in ...well...order 🤷🏽♀️
That's all awesome, but Scully does not know anything about it! When you installed Scully, it created a configuration file at the root of your app. Go find it! And edit it to look like this!
You're ready to generate the static pages!
Run Scully the first time to have the
docs content folder created for you.
Do it with
$ npm run scully
When you run Scully the first time, it creates the first post for you. It does this, because
schematics cannot create folders that are empty.
Let's create more stuff, to learn how to.
You don't really need to do this manually. That would be tedious! Just go to the CLI and run
$ ng generate @scullyio/init:post
This will prompt you to choose a name for your
post(in this case, doc) and the folder it should go to. As folder, select
When you do this, you'll see the magic happen. If you find your
docs folder, at root level, you'll see at least 2 markdown (.md) files. One will have as file name, the date of creation (that's the first auto-generated). The second one will be the one you created.
Those files will have a configuration, too, looking something like this.
This is YAML configuration. It represents the title, description, and state (published/unpublished) of your
post. You can configure an additional item, the slug, mapping to the path to your static file, like this
You can use it to give it SEO friendly or enhanced, URLs
But you said your requirement was to have code in your docs!
Yes! And you can!
Ok, maybe not the liquid tags you're used to! At least not yet. That's my current mission 🚀
But you can still have gist embeds in your static pages. You only need to disable Angular.
Yes! You read well! You can entirely disable Angular for super-fast static HTML rendering. And also to embed scripts in your markdown ;)
First of all, install this custom plugin by my GDE friend, Sam Vloeberghs. Do this with
$ npm install scully-plugin-disable-angular --save-dev
Then, update your configuration to use this plugin for THESE routes. Yes, exactly! You can have a fully dynamic app everywhere else but prevent the bootstrap for your docs.
$ ng build --prod --stats-json
The plugin uses the bundle stats to understand what to disable. Finally, run
$ npm run scully -- --scanRoutes
and get the latest content created or routes!
Don't forget you can have a local version of your static docs site running locally! You just need to start it with
$ npm run scully serve
Your static server will be running in port 1668 (by default, while your dynamic Angular distribution will do it, in 1868.
I have! You can see this site live here It's a proof of concept and nothing else, but it can help you get started!
Now because my code lives here in this repo, every time I push to it, CI/CD does the job, and my docs site will be up to date!
Yes, a basic frontend, I know, POCS are like that ;)...You can fork and make it better! Have fun!
You can also watch me talk about it, here!