statiqdev / website Goto Github PK

The grey boxes make the documentation hard to digest.

I think they are supposed to be an emphasis on code but they refer to files, arguments, folders, and even concepts. It's just too much.

It might be helpful to add a note to input/framework/configuration/settings.md about how the settings files are searched for starting in the working directory of the application, not in your Engine's RootPath.

My setup right now has a bit of an upside-down layout, my engine.FileSystem.RootPath is something like "../", as I have the dotnet application in a child directory.

Need to add all the latest features

Still need pages for adding shortcodes, events, etc. Make sure the entire set of bootstrapper functionality is documented.

Set up a Spreadshirt shop for kicks, need to add link to site: https://statiq.myspreadshop.com/

Have been looking into Statiq to see if it will work for a project I'm doing. Its looking very promising! I've used Hugo before but much prefer the look of the Razor templates and this should also allow some more complex stuff I'm hoping to be able to do.

Have had a few initial issues that are probably obvious but not having done any asp.net or Razor development before were not initially obvious for me:

1. If you are running preview mode on the site then if you change settings.yml then the changes are not picked up! I realise now that this must be because they are more of a fundamental .net thing that's done at startup. But I spent a lot of time trying to figure out why some custom items were showing up and some weren't!

2. Possibly this was due to 1) but the Layout setting was not working for me in settings.yml. I was trying to set up a theme and could not get the layout working for a couple of hours! But adding _ViewStart.cshtml made it work. If this is something that's necessary (I see it is used on your staticdev site) then would be good to document that for beginners. And perhaps also mention that the server needs restarting after adding the theme.

3. Is there a verbose mode that will output warning when calling GetString for keys that do not exist? And perhaps even detect that settings.yml changed and suggest restarting the server? A bit more of a walkthrough on setting up a theme would be amazing.

4. How do you purchase a license? There's a lot of info in the Licensing FAQ but I couldn't see any obvious 'pay here' links there. I want to use this to generate a help system for a commercial product - presumably that means a license is required?

Including how to postfix the minimum version tag to avoid conflicts with multiple themes

Like Wyam used to have. With categories. Include badges or other indications of Framework/Web/Docs as well as extension assembly if not core.

• Theme projects.
• Using IEngineInitializer to modify engine.
• Using IThemeInitializer to register services, etc.
• Using .cs files in theme to create pipelines, etc. (see Statiq site ReleaseNotes.cs).

In the Statiq Web section on templates, better document the Markdown template and how to add extensions to it.

• Adding via the bootstrapper and RenderMarkdown module.
• Adding via settings or metadata on a document using the new MarkdownExtensions metadata.

Statiq has robust, totally undocumented testing support.

• Testing modules
• Testing entire builds with Bootstrapper.RunTestAsync()
• Testing content/output

https://github.com/statiqdev/statiqdev.github.io/blob/91f859804f6eafdc1ebe0a574d65f7c25dca58bf/input/web/deployment/azure-app-service.md#L50

As the cleanblog created summary HTML files with the same name as folders, the above redirect rules failed to rewrite to the posts.html and the tags.html. I'm not sure if the right option is to change the cleanblog theme to create the posts.html as index.html in the posts folder and tags folder, but for the moment, the redirects below solved my problems.

<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="html">
          <match url="(.+)/?" />
          <conditions logicalGrouping="MatchAny">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" />
          </conditions> 
          <action type="Rewrite" url="{R:1}.html" />
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>

Explains concepts like pipelines, modules, etc. Maybe just the first guide index page.

Using code analysis

As a new Statiq user, I'd like to know how to create a simple reusable layout without downloading a full-fledged theme, so that I can make my site look nice without unnecessary bloat.

Even just a sentence or two somewhere around "use the standard ASP.NET/Razor concepts: _ViewStart, _ViewImports, _Layout" could be a helpful pointer in the right direction.

See statiqdev/Statiq.Web#967

• Add a separate page explaining .statiq files and the use cases
• Explain that .statiq extension is dropped
• Explaining that .statiq files are always read, even if they start with an underscore and add a note to https://www.statiq.dev/web/content-and-data/ about it
• Show an example of using ContentType and MediaType to treat the .statiq file as something different

• Need to mention (and show in example) that the default still needs to be included
• Mention use cases like copying a file with an underscore (see statiqdev/Discussions#99 (reply in thread))

I was looking at this section: https://statiq.dev/framework/documents/accessing-metadata#metadata-lookup

The description is not entirely accurate. It gives the impression that ToLookup picks up multiple values in the meta data, but after some testing I found it only picks up the first. To create a lookup when there may be multiple values in the metadata item ToLookupMany should be used.

See statiqdev/Statiq.Framework#99 and statiqdev/Statiq.Web#939

https://realfavicongenerator.net/favicon_checker?protocol=https&site=statiq.dev%2F#.XxMcXSgzaMo

See statiqdev/Statiq.Framework#205

• Compilation is always cached, this caches rendering output
• Use when rendering a partial is time-consuming
• Explain why and when to use a cache key
• Explain how model is the cache key if alternate isn't provided

Similar to modules using code analysis.

As a new Statiq user, I'd like a one-stop shop to know what options I can add to my appsettings.json file, so that I can most efficiently configure my site.

I was able to figure out what I needed by browsing the framework code, but it'd be great if the full list was laid out and described somewhere handy!

https://statiq.dev/web/
Step 3: Install Statiq.Web

I get an error logged when I try and use the example from https://www.statiq.dev/guide/web/content-files/links-and-cross-references#changing-the-default-cross-reference-name (specifically the _directory.yml one)

Xref: => Config.FromDocument(doc => doc.Destination.FileNameWithoutExtension.Replace(' ', '-'))

Error:

[ERRO] 1 errors compiling script:
Line 1: CS1929: 'NormalizedPath' does not contain a definition for 'Replace' and the best extension method overload 'MemoryExtensions.Replace(in Memory<char>, char, char)' requires a receiver of type 'in Memory<char>'
[ERRO] Content/PostProcess » RenderContentPostProcessTemplates » ResolveXrefs » Exception of type 'Statiq.Core.ScriptCompilationException' was thrown.
[ERRO] Archives/PostProcess » ExecuteSwitch » RenderContentPostProcessTemplates » ResolveXrefs » Exception of type 'Statiq.Core.ScriptCompilationException' was thrown.

I changed the setting to this (adding the .GetTitle()) and the error was resolved:

Xref: => Config.FromDocument(doc => doc.Destination.FileNameWithoutExtension.GetTitle().Replace(' ', '-'))

Similar to the Wyam docs on this topic

See statiqdev/Statiq.Framework#192

I noticed that none of the assets or mirrors are cached on statiq.dev, so big things like mermaid.js are being downloaded on every single request, which can take a while on slower connections (crappy cellular/satellite). These are all the uncached requests when hitting the home page a second time:

It looks like the cache-control header for the whole site is public, max-age=0, must-revalidate - I'd suggest caching everything for at least a couple hours by default, and stuff under /mirror for a fairly long time (months?), since those libraries are inherently versioned.

There's no standard syntax, so it'd be helpful to document what is supported by the current parser.

For example, ++ for underline.

While not strictly a theme thing, it's most helpful for themes so document the sass- prefix metadata in the theme section. In clude discussion of !default Sass syntax and how it works well with the injected Sass variables from metadata.

Looks funny, probably because of float on badge

A lot of users will be migrating from Wyam - the docs should point out the benefits of updating and explain the big differences (and similarities) between Wyam and Statiq.