statiqdev / docable Goto Github PK

Add optional full-featured blogging support.

Since this theme is based on Bootstrap it makes sense to enable the bootstrap Markdig extension to have things like tables or blockquotes styled using Bootstrap styles.

AddSetting(Statiq.Markdown.MarkdownKeys.MarkdownExtensions, "bootstrap")

This could be mentioned in the README.

Hi,

I have followed the getting started doc for Statiq.Docs website, and cloned the Docable theme as a submodule:

 git submodule add https://github.com/statiqdev/Docable.git theme

But I am now receiving an error when starting the website:

[ERRO] Content/PostProcess » RenderContentPostProcessTemplates » ExecuteIf » ExecuteIf » RenderRazor » [C:/code/tests/connect.statiq/theme/input/index.cshtml => index.html] Value cannot be null. (Parameter 'key')
[DBUG] Exception while executing pipeline Content/PostProcess: System.ArgumentNullException: Value cannot be null. (Parameter 'key')
   at System.ThrowHelper.ThrowArgumentNullException(String name)
   at System.Collections.Concurrent.ConcurrentDictionary`2.GetOrAdd[TArg](TKey key, Func`3 valueFactory, TArg factoryArgument)
   at Statiq.Common.ConcurrentCache`2.GetOrAdd(TKey key, Func`2 valueFactory)
   at Statiq.Common.IDocumentExtensions.GetTitle(IDocument document)
   at AspNetCore._Shared__RightNavigation.ExecuteAsync() in Shared/_RightNavigation.cshtml:line 12
   at Microsoft.AspNetCore.Mvc.Razor.RazorView.RenderPageCoreAsync(IRazorPage page, ViewContext context)
   at Microsoft.AspNetCore.Mvc.Razor.RazorView.RenderPageAsync(IRazorPage page, ViewContext context, Boolean invokeViewStarts)
   at Microsoft.AspNetCore.Mvc.Razor.RazorView.RenderAsync(ViewContext context)
   at Microsoft.AspNetCore.Mvc.ViewFeatures.HtmlHelper.RenderPartialCoreAsync(String partialViewName, Object model, ViewDataDictionary viewData, TextWriter writer)
   at Microsoft.AspNetCore.Mvc.ViewFeatures.HtmlHelper.PartialAsync(String partialViewName, Object model, ViewDataDictionary viewData)
   at AspNetCore._Shared__Navigation.ExecuteAsync() in Shared/_Navigation.cshtml:line 23
   ...

I have cloned the theme in my project directory:

.vscode/
bin/
cache/
input/ <= single index.md
obj/
output/
temp/
theme/ <= submodule
wwwrooot/
.gitmodules
Connect.Statiq.csproj
Program.cs

Is this layout correct? It seems statiq tries to read the theme/input/index.cshtml from the submodule which is empty

When opening search page it would be convenient if search field has the focus so that the user directly can start searching

This is separate from content search in #5, though it would be cool to provide a combined search that shows both as well.

Hey, it's me again (from the Samson repo) :-)

As I understand it this is the theme to use once Statiq.Docs is ready to generate documentation from C# xml comments?

1. Blog?
   I now have a site where I can navigate my structure of markdown input files, but in my Wyam site I also have the blog (entered via link in the top level navigation). Can I achieve that here (preferrably without building another site with the CleanBlog theme...)?

2. Navigation issue
   Also, I have this input structure:
   

But for the "backend" folder both "Backend" and "Architecture" comes out in top navigation. The top level files under infrastructure does not show in top navigation. I have no files where ShowInNavigation is set to false.

Why is "Architecture" rendered in top navigation?

For the search page there's currently an "Edit this Page" link shown in the right sidebar, even though the user won't be able to edit the page.

Hi,

When added the search generation to the my doc I can see the title in results but there res.excerpt is undefined

screenshots:

ref PR: /pull/17

and the object received from res is

{
    "link": "/guide/exceptions",
    "title": "Handling Exceptions",
    "ref": "935580395",
    "score": 0.21581771408826872,
    "matchData": {
        "metadata": {
            "database": {
                "content": {}
            }
        }
    }
}

settings.yml

GenerateSearchIndex: true

fe480ef changed the logic to determine the section that by default always only the API will be shown in the sidebar, even when a Markdown content page is shown.

To reproduce:

• Create a new project following quickstart as documented at https://www.statiq.dev/docs
• Use Docable theme
• Add some Markdown content pages and provide some source files
• Open website for a content page

Available via toggle and also OS setting. Should remember (via cookie? local storage?) if user selects the toggle.

Ideally appears after scrolling a bit and stays fixed to bottom corner

What license is Docable licensed under, if any? I've been customizing it a bit and may want to publish a new theme at some point, but at the moment I can't do that since I've used Docable as a base.

Sidebar currently lists all pages two levels deep. Based on content this list can become quite long. In such scenarios it could be helpful to have a parameter to enable that list is collapsible.

The link to the Statiq.Web configuration settings (https://www.statiq.dev/web/configuration/settings) ends in a 404

I kind of like the style with anchor link icons that show when you hover

I'm previewing with --virtual-dir=Cake.7zip set and I have setting Logo=/assets/logo.png.

The logo is rendered as:

<img id="logo" src="/assets/Logo.png" alt="Documentation">

Which results in 404/NotFound for the logo.
Manually changing the src to /Cake.7zip/assets/Logo.png does result in the logo being visible.

It would be nice if on a page load sidebar would scroll so that the current active navigation item is visible

The output folder for my statiq site is in a folder that is served as a subfolder of another asp.net mvc site. That project has code that requires user to be logged in to access the statiq site. When using the Docable theme, clicking any link within the site throws me out to the login page. After some digging around and debugging I found that the issues are with "requests made from quicklink" (?), as they seem to not include the session information my login check requires.

Commenting out the quicklink parts in the _Layout file solved my issue.

Currently in the right sidebar it lists all headings of level 1. It would be nice to have the possibility to define which level should be shown (e.g. if Markdown files are written with H1 for title and H2 should be listed there)

Currently two levels are shown in sidebar. Depending on the content it could make sense to have more or less levels shown. It would be nice to have an option to define how much levels are shown.

Setting page is currently shown in navigation and needs to be overwritten in page to hide from navigation. It would be nice to have a setting to control if API page is shown in navigation or not

Hi again,
After pointing the SourceFiles setting to the right folder I'm getting the "api" generation running,
but when it runs I'm getting lots of errors like these ones;

The code base is quite large, and it seems the error is thrown for pretty much every class. Due to all these errors it's taking too long time to try to even finish the generation.

I tried to point the source files back to the statiq project itself, and that gives me a successful docs generation of the .cs files within the docable theme.

I'm really not sure what it is in my codebase that would cause these errors...

Currently there are a bunch of links hardcoded in the _Layout.cshtml page which require the corresponding files to be provided by the actual site.

        <link rel="apple-touch-icon" sizes="180x180" href="@Context.GetLink("/assets/favicons/apple-touch-icon.png")">
        <link rel="icon" type="image/png" sizes="32x32" href="@Context.GetLink("/assets/favicons/favicon-32x32.png")">
        <link rel="icon" type="image/png" sizes="16x16" href="@Context.GetLink("/assets/favicons/favicon-16x16.png")">
        <link rel="manifest" href="@Context.GetLink("/assets/favicons/site.webmanifest")">
        <link rel="shortcut icon" type="image/png" href="@Context.GetLink("/assets/favicons/favicon.ico")"/>
        <link rel="mask-icon" href="@Context.GetLink("/assets/favicons/safari-pinned-tab.svg")" color="#e9ecef">

It would be nice if it can be configured which links should be added, so that only links can be added which are needed by the page, without copying whole _Layout.cshtml.

Similar to what Chocolatey does

When a heading contains a special character (e.g. &) the HTML entity (e.g. &) is shown in the right sidebar instead of the character

Defined via front matter? Should be able to use an xref or output path.

The /assets links in the _Layout file of this theme is not correct when using the LinkRoot setting. I believe they should be rendered via Context.GetLink.

It would be nice to have configuration option to have the header sticky to the top.

When running Statiq.Docs 1.0.0-beta3 with Dockable c7d11df, the SiteKeys and SectionNames conflict with similar classes in the main Statiq library.

[ERRO] Content/PostProcess » RenderContentPostProcessTemplates » ExecuteIf » ExecuteIf » RenderRazor » _Layout.cshtml(20,50): error CS0433: The type 'SiteKeys' exists in both 'Docable, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null' and 'Docs, Version=1.4.0.0, Culture=neutral, PublicKeyToken=null'
[ERRO] Content/PostProcess » RenderContentPostProcessTemplates » ExecuteIf » ExecuteIf » RenderRazor » _Layout.cshtml(40,35): error CS0433: The type 'SectionNames' exists in both 'Docable, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null' and 'Docs, Version=1.4.0.0, Culture=neutral, PublicKeyToken=null'
[ERRO] Content/PostProcess » RenderContentPostProcessTemplates » ExecuteIf » ExecuteIf » RenderRazor » _Layout.cshtml(46,41): error CS0433: The type 'SiteKeys' exists in both 'Docable, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null' and 'Docs, Version=1.4.0.0, Culture=neutral, PublicKeyToken=null'
[ERRO] Content/PostProcess » RenderContentPostProcessTemplates » ExecuteIf » ExecuteIf » RenderRazor » _Layout.cshtml(47,38): error CS0433: The type 'SiteKeys' exists in both 'Docable, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null' and 'Docs, Version=1.4.0.0, Culture=neutral, PublicKeyToken=null'

There are still a few places where lists of symbols aren't sorted (like the sidebar: https://github.com/Wyamio/Samson/blob/3ba3e41daec978228c0a6de7f08f3fd03ab0ae3d/Shared/Sidebar/_Member.cshtml#L38-L41). Audit all uses of symbols and sort them where possible so that rebuilds don't change the order.