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.
There are plenty of nice documentation platforms out there, but some of them are on paid schemes. There are also a few static pages generators specially designed for documentation, but they're written in other javascript frameworks.
I want my own site, written in Angular!
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
Angular + Scully to the rescue!
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!
Prerequisites
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!
Leveraging the in-built contentFolder plugin, and the markdown plugin.
The next thing we will do is creating a new module called docs
$ ng generate module docs --route=docs --module=app-routing
Awesome!
Now we will go to the docs.component.html template, and make sure to add the mandatory Scully injection tag
<scully-content></scully-content>
Beautiful!
We will also create an additional component called sidenav, to maintain our dynamic side navigation
Side Navigation, is important
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 🤷🏽♀️
Configure Scully
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!
Create more awesome stuff!
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 docs.
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.
Markdown has its config, too!
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
Gists in the markdown
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.
Excuse me? 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.
Done!
Now run
$ 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!
Local Server Scully
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.
Netlify your docs!
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!
Top comments (1)
Hi Sebastian! Great stuff!
This is also a proof of concept I laid out in about 1 hour, but people are free to grab it and improve it or use it as they see fit.
I think SSG is changing the game a providing a solution to needs like the one you have, in a very simple way.