Samples? Finding it hard to know how to start.

[pjmagee]

Hi, where can I find samples of all the different modules and pipelines? It's really difficult to get started. I have a lot of JSON files which I would like to use as a base for generating many html output files via razor. I'm comfortable with Razor and it means I will be able to produce the correct html based on what the JSON structure is like, since each json file doesnt always have the same data.

Anywhere to get started? I looked a lot on the website and the guide section but I'm still not finding an easy way to begin.

[daveaglick]

In general, Statiq Web is structured in a way that most of the pipeline and module stuff (at least creating or editing them yourself) is abstracted away from you (much like every other static site generator - I.e. it's not common to crack open Jekyll to change how it works). That said, the internals are there for use when the default set of features doesn't satisfy. In this case though, it sounds like you can probably get by with the built-in features of Statiq Web.

Hopefully you've been able to get a boilerplate up and running by following the quick start. At that point you should be able to generate a site (a mostly empty one, but still) by calling dotnet run on the command line. Have you been able to get this far?

From there it's a matter of adding the right files to the input folder and making use of the way Statiq handles documents and makes them available through pipelines. I would start by adding the JSON files you want to the input folder (they can go directly under input or in a subfolder). That will let Statiq pick them up as data files and they'll be exposed via the "Data" pipeline. This section has code showing how to access your data files as documents inside a Razor file, for example. The content of the JSON file will be exposed as metadata in the resulting documents.

Once the JSON files are being processed as data files inside Statiq and the resulting document exposed through the "Data" pipeline, you can use them in a Razor file. One way would be to write a single Razor file that iterates them all and renders content based on them. It sounds like you want to do something more like multiple outputs per JSON (or even per individual JSON object) though. There's a few facilities you can use for that:

• Archives is intended for situations where you want to aggregate multiple documents (I.e. the JSON files) into lists based on filtering/sorting/paging.
• Enumerating can be used to create additional output files over some set of input values (such as your JSON documents or items within your JSON files). In this case you'd probably want to use computed values to get and enumerate the JSON documents - something like Enumerate: => ExecutionState.Outputs..FromPipeline("Data")....
• You could change the content type to "Content" which won't process the JSON files as a "data file", but instead treat them like content files that should be rendered. This can be a little trickier and might require a custom pipeline since you'll want to load the JSON, process it as JSON to populate the document metadata, and then render it as if it were a Razor file so you can pickup a _Layout.cshtml.

In any case, there are probably several ways to accomplish what you're looking to do and the "right" one is more a matter of preference and the specific use case.

As far as examples go, there are several sites build on Statiq that do similar-ish things:

• The .NET Foundation site renders their individual project pages by using Markdown files per project and embedding common attributes in the front matter of those, which then get rendered in a common style using a _Layout.cshtml: https://github.com/dotnet-foundation/website/blob/main/input/projects/data/_Layout.cshtml
• Discover .NET uses a custom pipeline for rendering pages for each project, as specified in YAML files: https://github.com/daveaglick/discoverdotnet/blob/master/Pipelines/Projects/Projects.cs (notice the use of the ParseYaml() module followed eventually by the RenderRazor() module).
• There are many blogs that serve as an example of simpler use cases and out of the box functionality: https://github.com/daveaglick/daveaglick
• The Statiq repository also has some rudimentary examples embedded in a single Statiq site, mostly demonstrating the use of the archive feature until I get around to adding more: https://github.com/statiqdev/Statiq.Web/tree/main/examples/Statiq.Web.Examples

I'd recommend cloning any one of those and trying to dissect it a bit to understand what's going on.

Does that help at all? Let me know if you have more details about your specific use case and we can maybe dive a little more in-depth once you've had a chance to look at some of the existing sites.

[pjmagee]

Hi, I've just read through your response, this is very helpful thank you!

[daveaglick]

Great! Happy to keep assisting after you have a chance to digest everything.

[pjmagee]

Okay, so I kind of understand the layers now. Still finding it difficult to understand how enumeration works. I have managed to produce an index file but it will not enumerate my json files to produce new cshtml files. Only one file gets created called index.html that I have put a razer loop of the output files so the index contains <ul> <li> ... </li> </ul> of each file. But no luck on the enumerating. Ive tried several things and a custom pipeline and ended up just outputting the json files to the output folder but couldnt get that them to use a Layout or cshtml file.

Really, I think if there was a samples directory that showcased each individual feature thats possible I might be able to get by, but because it's a mixture of declarative and logic I'm just struggling. I got a simple blog site up that is using Statq, which I am using and have posts, but I did not need to understand anything about it, it was super easy to use. But now im trying to do something more barebones and really all I want is to enumerate json files, have each json file get processed by a layout and then maybe the layout will call a different render section depending on what type of json file it is. I cant do it. I'm just stuck no matter how much documentation I read. I guess I've always been better at consuming and understanding how something works by examples instead of reading documentation.

Eventually, the input folder is going to be pretty huge, over 100,000 json files. Sub folders two, categorising that type of json files are inside that folder. My plan was to process all these files into html files and calculate links between them all, since many json files may be related to any other json file in any category.

[pjmagee]

I have really tried to understand, I've spent all day and have not got anywhere, I did manage to actually dump all the files out! ...but only because I changed their content type by putting a _directory.yml with the ContentType: Content. Obviously, i thought inside here I would define a Layout: _layout.cshtml and maybe trigger the documents to go through cshtml but they all came out as html files with just the JSON.

I had a sneaky look at all the dependencies of Statiq.Web on Github and you can see everyone's project which is using Statiq.Web but I dont think ive seen any examples that are trying to do what I am doing, so there's no code I can use as a reference. :(

[pjmagee]

Okay, I made some progress!

[harperjohn]

@daveaglick I feel that I am just getting in to the same boat as @pjmagee .

I am very interested in this project, and I want to contribute... maybe my first contribution(s) can be examples, a FAQ, and a Theme example walk through.

I am assuming that you have ideas/progress in these areas, and maybe we can chat about this so I add to what you have started/planned

[daveaglick]

@harperjohn All of that onboarding stuff is great to take on and any help is appreciated - it's the one area where I feel like there's a lot more work still to do.

I think one of the biggest challenges is helping people understand that this is a big complex framework, and like any big framework (think ASP.NET) there are a lot of different ways to do things, little tricks and hacks, poorly documented features, etc. But there's also (hopefully) some easy happy-paths to get up and running with a minimal amount of ceremony as well. If the latter is hard to figure out, then that's on me and the project - I don't want new users to have to work too hard or think too hard to get a simple blog out the door. After that, the learning curve can be as steep as they want, but the initial bit should be smooth.

[harperjohn]

@daveaglick Yes - it is such a delicate balance... in the beginning you need to reach critical mass/momentum to get anything done... but then once you get enough info/experience to get started, there is this temptation (even obsession) to "learn everything"... and this is where "the perfect becomes the enemy of the good". It is a battle that I regularly deal with!

I have a bit more to say... but it occurs to me that I probably should (at least for now) keep this discussion going in my "Congo for Statiq" topic/thread.