Lots of questions

[AceTheWiz]

Hi Dave, I know you are actively working on this and one man only has so much time :) I am just itching to get something working. I will understand if you cannot provide answers now.

Anyway I experimented with Wyam and now Statiq Framework and just yesterday Statiq.Web. I must say I like the direction of Statiq.Web. I have the basic generation working but need to tweak a few things. If you have time a few quick pointers would be great.

My content contains markdown, images and some json data files (hoping to render this using Razor).

Short Term Questions

1. How do I pass configuration settings ? You mention appsettings.json but I found no reference in the code. I want to change paths, exclude folders etc
2. How do I get the themes working ? I have passed the theme folder as an arg but it is ignored.
3. How do I temporarily disable some pipelines (e.g. Data, Feeds, Less, Sass) while I'm focusing on content only.

Longer Term Questions

(which will probably be answered in the docs soon(ish) "In your words" :)

1. I will want to use Razor to render but have no clue how to get Statiq to include it.
2. I want to use the Hierarchical navigation features as well.

[daveaglick]

Great questions! I'll do my best to answer each one...

How do I pass configuration settings?

By far the easiest way is to use the Bootstrapper. For example, to set the host for your site (important when generating absolute links for things like RSS feeds):

await Bootstrapper.Factory
  .CreateWeb(args)
  .AddSetting("Host", "statiq.dev")
  .RunAsync();

The boostrapper has a ton of different fluent methods that can be used to add settings, add shortcodes, create and add pipelines, manipulate the engine, etc.

You mention appsettings.json

An appsettings.json file is indeed supported and any key-value pairs inside of one will result in settings. The same goes for environment variables - any environment variables will also be automatically added as settings (which is helpful for things like CI builds).

I want to change paths, exclude folders etc.

The appsettings.json file can only create settings - it can't manipulate the engine or perform more complex configuration. That's where other bootstrapper methods come in. For example, to add another input path:

await Bootstrapper.Factory
  .CreateWeb(args)
  .ConfigureEngine(x => x.FileSystem.InputPaths.Add("another-path"))
  .RunAsync();

The globbing patterns that are used to locate files for the Content and Data pipelines are not currently configurable, but will be soon. That's one my shortlist of stuff to make configurable.

How do I get the themes working?

There's no real theming support right now. Old Wyam themes won't work with Statiq (and that's a good thing - Statiq actually makes theming much easier, I just need to add some tooling and examples). At the moment, Statiq Web does add a secondary "theme" folder to the set of input folders, but as far as I know no one has actually written a theme to go in it. Still, it's not a bad idea to put your general layout files in that folder and your content files in the "input" folder just to give some separation.

How do I temporarily disable some pipelines (e.g. Data, Feeds, Less, Sass) while I'm focusing on content only.

You can't really "disable" pipelines since many have dependencies on other ones. You can specify a subset of pipelines (and their dependencies) to run though:

dotnet run -- preview content

That command will only build the Content pipeline (and it's dependencies) and then launch the preview server. Note that the output folder is cleared on each build so if you do this, you won't get a usable site since things like assets won't be generated or copied.

I will want to use Razor to render but have no clue how to get Statiq to include it.

Razor is included in Statiq Web by default, just name your files with a .cshtml extension. If you want to use Razor in a Statiq Framework application, reference the Statiq.Razor package and use the RenderRazor module.

I want to use the Hierarchical navigation features as well.

In Statiq Web, documents from the Content pipeline are organized in a tree structure to make this sort of thing easier. You can do something like this (in Razor) to render a tree navigation:

Hope that was all helpful! Feel free to follow-up with any more questions.

[AceTheWiz]

Thank you for the response Dave, definitely helpful.

Must admit though it is still a bit of a "magical" black box to me. Even though I have read the documentation and have a high level understanding of the major concepts such as pipelines, modules and documents, I still haven't reached that Aha ! point where I can go beyond just extending the examples. Also being relatively new to C# also doesn't help.

I will patiently wait and keenly watch for updates.

p.s. If Issues are the wrong place for this kind of exchange just let me know.

Cheers Alan.

[gep13]

@AceTheWiz you might be interested in taking a look at @mholo65”s blog post here:

https://twitter.com/mholo65/status/1252234036736483328?s=21

Which digs into how some things work.

[daveaglick]

If Issues are the wrong place for this kind of exchange just let me know.

Issues are perfect right now - I like questions to be visible so they can help other people (and so I see them) and the issue tracker is the best place right now for that. I keep hoping GitHub opens their discussions beta to more projects and will likely jump on board that as soon as it's available.

I still haven't reached that Aha ! point where I can go beyond just extending the examples.

Ideally you won't really need to. The underlying goal of Statiq Web (as opposed to using Statiq Framework) is that you won't need to extend it for most common scenarios, though the option is always available.

Documentation work is also my number 1 priority right now - in fact any features that've been added in the last week or two are probably directly related to getting Statiq's own site up and running. Nothing like a little dogfooding :).

[daveaglick]

Hopefully I was able to answer everything. The docs at https://statiq.dev are also a lot more complete now. I’ll go ahead and close this issue, just follow-up if I can answer anything else.