I would like to add support for comments to my blog via Utterances.

I think the way I am supposed to do it is with a custom component.

Utterances is enabled on a particular page by adding the following HTML.

<script src="https://utteranc.es/client.js"
        repo="[ENTER REPO HERE]"
        issue-term="pathname"
        theme="github-light"
        crossorigin="anonymous"
        async>
</script>

I think I have followed all the instructions for adding a custom component. My problem is that TypeScript doesn't think repo is a valid attribute of a script element.

TSError: ⨯ Unable to compile TypeScript:
.codedoc/components/utterances/index.tsx(11,18): error TS2322: Type '{ src: string; repo: string; "issue-term": string; label: string; theme: string; crossorigin: string; async: true; }' is not assignable to type 'ScriptAttributes'.
Property 'repo' does not exist on type 'ScriptAttributes'.

Conceptually, I know that I want to add tell the TypeScript type system to allow these attributes for this tag, but I don't know how to do that. I think it should be something similar to these top search results on SO, but I am not familiar enough with this to know how to apply these solutions for a site hosted by coding.blog.

Here is the branch that contains my attempt to get this working.

How can I enable Utterances on a page of a site hosted by coding.blog?

(My apologies if this is a standard tsx problem and the solution has nothing to do with coding.blog.)

I obtained the following screenshot from this page on my site.

I didn't expect there to be any white. There is no white in the demo of dark mode on utterances.

Is this a bug with CODEDOC or utterances?

I have over 150 headings on one page (automatically generated). The right navigation panel shows only few last ones (~40), cannot be scrolled to upper items and doesn't follow to upper items (headings before ~40 last ones).

The website can either be built for hosting locally or on GitHub. The APIs exposed for these two build pipelines are not the same...as least with respect to the assets folder.

When building the website for hosting on GitHub, any asset not created by codedoc can start anywhere in the repo and then be copied to the assets folder during the build.

When building the website for hosting locally, any asset not created by codedoc must already exist in the asset folder since there is no copy step in this case.

Here is an idea for how to unify these APIs. Add to DestConfig a path called existingAssets. Then part of the codedoc build process would be to copy the contents of that folder into the asset folder. Then this special step in the GitHub build process can be removed.

The goal I am trying to achieve is to have all the files I create for my blog be inside one folder (i.e. src) and no generated folders or files added to that folder by codedoc during a build.

Executing codedoc version says to execute codedoc update, which seems to execute successfully, but executing codedoc version again still says to execute codedoc update.

twilliams@EDMONDS MINGW64 /c/Code/Blogs/tyson-williams-blog (master)
$ codedoc version

# Fetching version info ...
# @codedoc/cli version 0.2.0 ...................................... latest: 0.2.0
# @codedoc/core version: 0.1.63 ................................... latest: 0.2.0

# WARNING: some packages are missing or need update.
# Please run codedoc update


twilliams@EDMONDS MINGW64 /c/Code/Blogs/tyson-williams-blog (master)
$ codedoc update

# Updating CLI ...
# Updating local codedoc installation ...


twilliams@EDMONDS MINGW64 /c/Code/Blogs/tyson-williams-blog (master)
$ codedoc version

# Fetching version info ...
# @codedoc/cli version 0.2.0 ...................................... latest: 0.2.0
# @codedoc/core version: 0.1.63 ................................... latest: 0.2.0

# WARNING: some packages are missing or need update.
# Please run codedoc update

I have 24 pages (including _toc.md, 404.md, and index.md), which doesn't feel like a lot, but it takes some time (not a ton on my desktop, but quite a bit on my laptop) on sequential, individual, file saves to rebuild the entire directory.

It would be awesome if only the files being saved were rebuilt!

I think this project should get added to Netlify's StaticGen indexer for static site generators: https://www.staticgen.com/

It looks like it passes all the requirements

What about adding support in code blocks to underline specific code with a red squiggle to communicate to the reader that this code doesn't compile?

I like to use the terminal Mintty (currently have version 2.9.6), which I open via GitKraken.

After executing npm i -g @codedoc/[email protected], I have the following installed

• codedoc/cli 0.2.0
• codedoc/core 0.1.63

Then executing codedoc update latest crashes. After which, codedoc isn't even installed.

twilliams@EDMONDS MINGW64 /c/Code/Blogs/tyson-williams-blog (master)
$ codedoc version

# Fetching version info ...
# @codedoc/cli version 0.2.0 ...................................... latest: 0.2.0
# @codedoc/core version: 0.1.63 ................................... latest: 0.2.0

# WARNING: some packages are missing or need update.
# Please run codedoc update


twilliams@EDMONDS MINGW64 /c/Code/Blogs/tyson-williams-blog (master)
$ codedoc update latest

# Updating CLI to latest version ...
npm ERR! code EPERM
npm ERR! Error: EPERM: operation not permitted, open 'C:\Users\twilliams\AppData\Roaming\npm\codedoc'
npm ERR!     at isClobberable (C:\Program Files\nodejs\node_modules\npm\node_modules\gentle-fs\lib\bin-link.js:55:3)
npm ERR!     at C:\Program Files\nodejs\node_modules\npm\node_modules\gentle-fs\lib\bin-link.js:38:27
npm ERR!     at Array.forEach (<anonymous>)
npm ERR!     at binLink (C:\Program Files\nodejs\node_modules\npm\node_modules\gentle-fs\lib\bin-link.js:38:13)
npm ERR!     at tryCatcher (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\util.js:16:23)
npm ERR!     at ret (eval at makeNodePromisifiedEval (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\promisify.js:184:12), <anonymous>:11:39)
npm ERR!     at linkBin (C:\Program Files\nodejs\node_modules\npm\node_modules\bin-links\index.js:126:10)
npm ERR!     at C:\Program Files\nodejs\node_modules\npm\node_modules\bin-links\index.js:91:12
npm ERR!     at tryCatcher (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\util.js:16:23)
npm ERR!     at MappingPromiseArray._promiseFulfilled (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\map.js:61:38)
npm ERR!     at MappingPromiseArray.PromiseArray._iterate (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\promise_array.js:114:31)
npm ERR!     at MappingPromiseArray.init (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\promise_array.js:78:10)
npm ERR!     at MappingPromiseArray._asyncInit (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\map.js:30:10)
npm ERR!     at _drainQueueStep (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\async.js:142:12)
npm ERR!     at _drainQueue (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\async.js:131:9)
npm ERR!     at Async._drainQueues (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\async.js:147:5)
npm ERR!  OperationalError: EPERM: operation not permitted, open 'C:\Users\twilliams\AppData\Roaming\npm\codedoc'
npm ERR!     at isClobberable (C:\Program Files\nodejs\node_modules\npm\node_modules\gentle-fs\lib\bin-link.js:55:3)
npm ERR!     at C:\Program Files\nodejs\node_modules\npm\node_modules\gentle-fs\lib\bin-link.js:38:27
npm ERR!     at Array.forEach (<anonymous>)
npm ERR!     at binLink (C:\Program Files\nodejs\node_modules\npm\node_modules\gentle-fs\lib\bin-link.js:38:13)
npm ERR!     at tryCatcher (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\util.js:16:23)
npm ERR!     at ret (eval at makeNodePromisifiedEval (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\promisify.js:184:12), <anonymous>:11:39)
npm ERR!     at linkBin (C:\Program Files\nodejs\node_modules\npm\node_modules\bin-links\index.js:126:10)
npm ERR!     at C:\Program Files\nodejs\node_modules\npm\node_modules\bin-links\index.js:91:12
npm ERR!     at tryCatcher (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\util.js:16:23)
npm ERR!     at MappingPromiseArray._promiseFulfilled (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\map.js:61:38)
npm ERR!     at MappingPromiseArray.PromiseArray._iterate (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\promise_array.js:114:31)
npm ERR!     at MappingPromiseArray.init (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\promise_array.js:78:10)
npm ERR!     at MappingPromiseArray._asyncInit (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\map.js:30:10)
npm ERR!     at _drainQueueStep (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\async.js:142:12)
npm ERR!     at _drainQueue (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\async.js:131:9)
npm ERR!     at Async._drainQueues (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\async.js:147:5) {
npm ERR!   cause: Error: EPERM: operation not permitted, open 'C:\Users\twilliams\AppData\Roaming\npm\codedoc'
npm ERR!       at isClobberable (C:\Program Files\nodejs\node_modules\npm\node_modules\gentle-fs\lib\bin-link.js:55:3)
npm ERR!       at C:\Program Files\nodejs\node_modules\npm\node_modules\gentle-fs\lib\bin-link.js:38:27
npm ERR!       at Array.forEach (<anonymous>)
npm ERR!       at binLink (C:\Program Files\nodejs\node_modules\npm\node_modules\gentle-fs\lib\bin-link.js:38:13)
npm ERR!       at tryCatcher (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\util.js:16:23)
npm ERR!       at ret (eval at makeNodePromisifiedEval (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\promisify.js:184:12), <anonymous>:11:39)
npm ERR!       at linkBin (C:\Program Files\nodejs\node_modules\npm\node_modules\bin-links\index.js:126:10)
npm ERR!       at C:\Program Files\nodejs\node_modules\npm\node_modules\bin-links\index.js:91:12
npm ERR!       at tryCatcher (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\util.js:16:23)
npm ERR!       at MappingPromiseArray._promiseFulfilled (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\map.js:61:38)
npm ERR!       at MappingPromiseArray.PromiseArray._iterate (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\promise_array.js:114:31)
npm ERR!       at MappingPromiseArray.init (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\promise_array.js:78:10)
npm ERR!       at MappingPromiseArray._asyncInit (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\map.js:30:10)
npm ERR!       at _drainQueueStep (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\async.js:142:12)
npm ERR!       at _drainQueue (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\async.js:131:9)
npm ERR!       at Async._drainQueues (C:\Program Files\nodejs\node_modules\npm\node_modules\bluebird\js\release\async.js:147:5) {
npm ERR!     code: 'EPERM'
npm ERR!   },
npm ERR!   code: 'EPERM'
npm ERR! }
npm ERR!
npm ERR! The operation was rejected by your operating system.
npm ERR! It's possible that the file was already in use (by a text editor or antivirus),
npm ERR! or that you lack permissions to access it.
npm ERR!
npm ERR! If you believe this might be a permissions issue, please double-check the
npm ERR! permissions of the file and its containing directories, or try running
npm ERR! the command again as root/Administrator.

npm ERR! A complete log of this run can be found in:
npm ERR!     C:\Users\twilliams\AppData\Roaming\npm-cache\_logs\2020-06-11T12_01_36_759Z-debug.log
(node:15252) UnhandledPromiseRejectionWarning: undefined
(node:15252) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). To terminate the node process on unhandled promise rejection, use the CLI flag `--unhandled-rejections=strict` (see https://nodejs.org/api/cli.html#cli_unhandled_rejections_mode). (rejection id: 1)
(node:15252) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

twilliams@EDMONDS MINGW64 /c/Code/Blogs/tyson-williams-blog (master)
$ codedoc version
bash: /c/Users/twilliams/AppData/Roaming/npm/codedoc: No such file or directory

The file mentioned in...

npm ERR! A complete log of this run can be found in:
npm ERR!     C:\Users\twilliams\AppData\Roaming\npm-cache\_logs\2020-06-11T12_01_36_759Z-debug.log

...is available here.

A Button that has a local URL should not open in a new tab. This behavior used to be correct since smooth loading would load all local URLs automatically. However, since smooth loading was updated to respect target attribute of local links, the default for buttons having target="_blank" becomes problematic.

Solution: simply check the URL and only add target="_blank" if it is not a local URL.

This is a spin off of issue #21.

CODEDOC uses chalk colors, and the default Windows Command Prompt displays them for me...

...but none of those colors are displayed when I use Mintty 2.9.6.

On both codedoc.cc, and coding.blog, after scrolling down for a few seconds, Chrome spontaneously crashes to the homescreen without error message. There is a brief blackscreen before the home screen appears.

Galaxy S6
Android 6.0.1
Chrome 79.0.3945.136.

This does not happen on any other site with this device.

Input (2 spaces after colon on a first line):

**Type parameters**:  
`U`: `any` Output [GGArray](#GGArray) item type

is rendered in a browser as:

<p><strong>Type parameters</strong>:  
<code>U</code>: <code>any</code> Output <a href="#GGArray">GGArray</a> item type</p>

It looks to me like those 2 spaces are outputted verbatim.

On the project docs is mentioned that CommonMark is supported, I think this is the relevant part: https://spec.commonmark.org/0.29/#example-630

Interestingly, in some other cases it does work:

**Parameters**:   
`f`: `FuncLike<T, U>` Mapping function  
`ctx`: `any` Context for function

Second hard line break is translated to <br>:

I edited an image (by cropping it) and then saved it while codedoc serve was running, but a rebuild was not triggered.

I think the build uses randomness to generate IDs. For example, this commit in my gh-pages branch contains a change from the first line to the second line.

...<script id="NLohRAMdsC">...
...<script id="QiJHwOFlpL">...

In fact, that commit was automatically created after I pushed a "no-op" change to master (...the only difference was the hashes in git). Therefore, no files in the gh-pages branch needed to be changed.

I would find it helpful when verifying changes and debugging problems if the commits in the gh-pages branch only contained necessary changes.

Is it possible to remove this randomness? If it is somewhat essential, maybe a seed to the underlying generator could be specified in configuration.

The problem

On certain web browsers, the blur effect used by the "Search the docs" button doesn't appear, making the resulting search window very hard to read. For example, on Firefox 68.7.0esr (the current built-in version that ships with Linux Debian 10.3):

The blur works just fine on Chromium 80.0.3987.162, for example.

Possible solution

If this is an inherent limitation of certain browsers' blur capability, it might be useful to detect whether the browser supports blurring. If it doesn't, then perhaps a simple opaque overlay could be used.

This is spin off of #30 (comment)

If I directly open my sample blog post, then the comments are displayed. But if I first open my home page and then navigate to the sample blog post, the comments are not displayed. A workaround is to refresh the page.

This is a bug with smooth loading mechanism of CODEDOC. Subsequent pages are loaded in the background and then the content (and other important parts) are replaced, to create a smooth and fast navigation experience. However, the container body is not replaced properly right now, which means scripts inside subsequently loaded containers are not executed normally. Inline scripts are manually executed, but right now there is no solution for remote scripts.

horizontal rulers do not display properly on the ToC. perhaps a specific css is required to make them work properly.

I expect that I will eventually want to "change" publically available URLs to my site. Either I will have a typo in some URL or want to change the structure.

Is there a way to specify a list of internal redirects?

As a hypothetical example, I would want to

• redirect https://tysonwilliams.coding.blog/this_is_speled_correctly
• to https://tysonwilliams.coding.blog/this_is_spelled_correctly

While codedoc serve was running, I created the code block...

```C#
```

...and then saved. Initially I received the error message

Language does not exist: C#

After a delay of a few seconds, I received this error message

Error:
 #
 # Unrecognized Language:: C#
 #
 # Check https://prismjs.com/#supported-languages for a list of supported languages.
 # You can also add --safe-highlight flag to snippets with unsupported langauges.
 #
    at Object.Code (C:\Code\Blogs\tyson-williams-blog\.codedoc\node_modules\@codedoc\core\src\components\code\index.tsx:53:22)
    at ComponentPlugin.create (C:\Code\Blogs\tyson-williams-blog\.codedoc\node_modules\@connectv\html\src\renderer\plugin\component\component.ts:39:25)
    at C:\Code\Blogs\tyson-williams-blog\.codedoc\node_modules\@connectv\html\src\renderer\extensible-renderer.ts:45:77
    at Array.some (<anonymous>)
    at ExtensibleRenderer.create (C:\Code\Blogs\tyson-williams-blog\.codedoc\node_modules\@connectv\html\src\renderer\extensible-renderer.ts:45:18)
    at Parser.tok (C:\Code\Blogs\tyson-williams-blog\.codedoc\node_modules\@connectv\marked\src\parser.tsx:75:16)
    at Parser.parse (C:\Code\Blogs\tyson-williams-blog\.codedoc\node_modules\@connectv\marked\src\parser.tsx:34:28)
    at C:\Code\Blogs\tyson-williams-blog\.codedoc\node_modules\@connectv\marked\src\index.ts:13:19
    at Object.<anonymous> (C:\Code\Blogs\tyson-williams-blog\.codedoc\node_modules\@codedoc\core\src\build\content.tsx:19:36)
    at step (C:\Code\Blogs\tyson-williams-blog\.codedoc\node_modules\@codedoc\core\dist\es5\build\content.js:44:23)
[ERROR] 20:50:35 Error:
 #
 # Unrecognized Language:: C#
 #
 # Check https://prismjs.com/#supported-languages for a list of supported languages.
 # You can also add --safe-highlight flag to snippets with unsupported langauges.
 #

After this, there was no longer any incremental rebuilds.

I expected that incremental rebuilds would continue.

The URL https://prismjs.com/#supported-languages in the error message was very helpful. It helped me realize that I should replace C# with csharp. If I make this kind of mistake again, I hope this URL is provided and incremental rebuilds continue working.

When locally serving my site, the page is reloading too much. Looking at the terminal, it is because codedoc serve is issuing a reload when files in the .git directory change.

# change in C:\Code\Blogs\tyson-williams-blog\.git\FETCH_HEAD, issueing reload to client ...
# change in C:\Code\Blogs\tyson-williams-blog\.git\objects\tmp_object_git2_a17264, issueing reload to client ...

I think that directory should not be watched for changes for all CODEDOC users.

In addition to that, I have another directory that I would like to not be watched. Sometimes I will include actual code in my repository to complement a post. With Visual Studio open, I keep getting messages like this.

# change in C:\Code\Blogs\tyson-williams-blog\src\code\IdentityAsAs\.vs\IdentityAsAs\v16\.suo, issueing reload to client ...

But even when I am causing the change, I don't need the website reloaded. When I make a change to source code file, a reload is issued. This codes exists as a reference both for me to test the claims I make in my post and for others to also test those claims and play with the code. No browser reloaded is needed.

# change in C:\Code\Blogs\tyson-williams-blog\src\code\IdentityAsAs\Project\Disambiguation.cs, issueing reload to client ...

As a side note, because my posts include the utterances script that calls the GitHub API on every page refresh, my IP is sometimes temporarily blocked by rate limiting. It isn't a problem for me, but I would prefer to be more respectful of GitHub's resources. Regardless of this reload issue, is there an easy why to disable the script when the site is locally hosted? I can split this off into its own issue if that would be better.

Hi first I like a lot your project,

I want to know if it's possible to display code block with languages like Sass because it built with prism.js

like so :

%btn {
  padding: .5em 2em;
  text-decoration: none !important;
  user-select: none !important;
  outline: none !important;
  cursor: pointer;
  transition: .4s;
}

It would be useful to be able to highlight a line as "added"/"removed"/"modified". Right now its just possible to highlight some particular lines.

Perhaps a syntax like /*+*/, /*-*/ and /*~*/ would be useful, similar to the syntax used for line highlighting.

Consider this function

but especially line 43

Is it correct that '.html' is always being appended to that file name?

I am playing around with the configuration and sometimes I get it wrong. Here is what one of the "Not Found::" error messages looks like for me.

# Not Found::
# /generated/bundle/codedoc-bundle.js
# C:\Code\Blogs\tyson-williams-blog\generated\generated\bundle\codedoc-bundle.js.html

On the topic of error messages, where are those beautiful colors? My error message doesn't have any red in it :(

Hi,
I like your work, awesome job! I wanted to setup a simple blog with my code and I noticed that node_modules have to be commited in the repo, which is something that I don't like (at least because of the size of the repo).

As I'm using Github Pages to host the blog I created Github Action pipeline, that takes the repo without node_modules, builds it and deploys it to the separate branch gh-pages. The benefit is that you don't have node_modules and html files, that are automatically generated, in your source code, but rather in the separate branch.

I think it is an elegant solution, so I just wanted someone know, that it is possible not to commit node_modules to the repo and utilize github actions instead.

• Repo
• config.ts
• pipeline

I see an approximately one pixel shear just above the bar in the footer when using

• Google Chrome 83.0.4103.106 with OS
• Android 7.0 and hardware
• LG K20V VS501.

I put a red rectangle around it in the screenshot below.

Auto rebuild stops working after renaming or deleting a markdown file. This happens to me when I want to create a new markdown file, and I achieve this by copy-pasting an existing markdown file and then renaming that file.

Here is an example where I copied sample-blog-post.md, pasted it as sample-blog-post - Copy.md, and then renamed it.

twilliams@EDMONDS MINGW64 /c/Code/Blogs/tyson-williams-blog (master)
$ codedoc serve

# Serving ...
# Fetching project configuration ...
Using ts-node version 8.10.2, typescript version 3.9.5
# Serving docs on http://localhost:3000
# building ........ src\markdown\404.md
# built:: ......... dist\404.html
# building ........ src\markdown\about.md
# built:: ......... dist\about.html
# building ........ src\markdown\index.md
# built:: ......... dist\index.html
# building ........ src\markdown\sample-blog-post.md
# built:: ......... dist\sample-blog-post.html
# building ........ src\assets\styles\codedoc-styles.css
# built:: ......... src\assets\styles\codedoc-styles.css
# building ........ src\assets\bundle\codedoc-bundle.js
# built:: ......... src\assets\bundle\codedoc-bundle.js
# Documents built!
# Changes in src\markdown\sample-blog-post - Copy.md queueing ...
# Rebuilding due to changes ...
# rebuilding ........ src\markdown\sample-blog-post - Copy.md
# rebuilt:: ......... dist\sample-blog-post - Copy.html
# Documents Rebuilt!
# Changes in src\markdown\sample-blog-post - Copy.md queueing ...
# Rebuilding due to changes ...
# rebuilding ........ src\markdown\sample-blog-post - Copy.md
Error: ENOENT: no such file or directory, open 'C:\Code\Blogs\tyson-williams-blog\src\markdown\sample-blog-post - Copy.md'
[ERROR] 20:58:06 Error: ENOENT: no such file or directory, open 'C:\Code\Blogs\tyson-williams-blog\src\markdown\sample-blog-post - Copy.md'

Attributes and their values can appear on the same line separated by a comma. They can also appear on separate lines but the commas are still required.

I like how F# handles this. For example, consider the two ways to define a record type. If a multiple field-type pairs are on the same line, they must be separated by a semicolon, but when they are on separate lines, then also separating them with a semicolon is optional.

The problem with these commas in the presence of new lines is that they are redundant: they are not DRY.

This is a spin off from issue #17

Quoting #17 (comment)

On the topic of error messages, where are those beautiful colors? My error message doesn't have any red in it :(

I am using Windows. I use GitKraken to launch a terminal. It opens Mintty 2.9.6.

There are many colors just above each prompt...

...but not for error messages from codedoc.

Currently the dark and light images in the DarkLight component are not ordered properly, as a result opening the image link will get weird results (opening the dark-mode image when in light mode and vice-versa).

It should be fixable by simply adding a higher z-index property to the visible div.

CONNECT-platform/coding-blog#19

The dark container of DarkLight component depends on its content for width scaling, which in cases might result in 0 width. It should instead scale to fill all possible width like the light container.

There is a particular design aspect of the .NET Core CLI that I like. By default,

• executing dotnet build implicitly executes dotnet restore and
• executing dotnet publish implicitly executes dotnet build.

I like this API because I think it makes it easier to achieve the behave the user actually wants. I prefer this behavior when I am manually executing commands.

But sometimes it can be helpful to execute a build without a restore or a publish without a build. This is possible by executing

• dotnet build --no-restore and
• dotnet publish --no-build (which implicitly sets --no-restore).

I prefer this behavior when doing automated builds, because when some part fails, I think it is easier to determine what part failed.

What about changing the codedoc CLI to behave similarly?

The problem

It looks like there are some weird behaviours with the page-level links on certain browsers. On Chromium 80.0.3987.162, the links are either unclickable or clickable only in very specific parts of the element:

In Firefox 68.7.0esr, the links work just fine:

What about markdown support for en dash (–) and em dash (—) via the input of two dashes (--) and three dashes (---) respectively?

Pending this issue, we should add support for custom inline components to codedoc and also add support for inline formulas.

I really like the list of headings that is displayed when viewing a CODEDOC site on a desktop. I far as I can tell, this list is not exposed on mobile.

I think it would be great if there were a good way to expose it.

As an example, the Wikipedia app on Android has a similar footer bar. It includes a hamburger menu on the right side the displays the list of headings. This menu can also be opened by starting on the right side of the screen and swiping to the middle.

* a
```gdscript
b

# comment
c
```

results in:

It seems to work in CommonMark:

https://spec.commonmark.org/dingus/?text=*%20a%0A%60%60%60gdscript%0Ab%0A%0A%23%20comment%0Ac%0A%60%60%60%0A

$ codedoc -v

# Fetching version info ...
# @codedoc/cli version 0.2.1 ...................................... latest: 0.2.1
# @codedoc/core version: 0.2.1 .................................... latest: 0.2.1

When I create code block with programming language annotation, which is not known to prism, the build throws exception.

For example using: "```log" results in following exception

Language does not exist: log
TypeError: Cannot read property 'rest' of undefined
    at Object.tokenize (/Users/lukas/repos/blog/.codedoc/node_modules/prismjs/prism.js:340:22)
    at Object.highlight (/Users/lukas/repos/blog/.codedoc/node_modules/prismjs/prism.js:334:18)
    at Object.Code (/Users/lukas/repos/blog/.codedoc/node_modules/@codedoc/core/src/components/code/index.tsx:49:28)
    at ComponentPlugin.create (/Users/lukas/repos/blog/.codedoc/node_modules/@connectv/html/src/renderer/plugin/component/component.ts:39:25)
    at /Users/lukas/repos/blog/.codedoc/node_modules/@connectv/html/src/renderer/extensible-renderer.ts:45:77
    at Array.some (<anonymous>)
    at ExtensibleRenderer.create (/Users/lukas/repos/blog/.codedoc/node_modules/@connectv/html/src/renderer/extensible-renderer.ts:45:18)
    at Parser.tok (/Users/lukas/repos/blog/.codedoc/node_modules/@connectv/marked/src/parser.tsx:75:16)
    at Parser.parse (/Users/lukas/repos/blog/.codedoc/node_modules/@connectv/marked/src/parser.tsx:33:28)
    at /Users/lukas/repos/blog/.codedoc/node_modules/@connectv/marked/src/index.ts:13:19
[ERROR] 19:34:45 TypeError: Cannot read property 'rest' of undefined

I would suggest not throwing exception, but rather to fallback on the default - non-highlighted code block.
Why - for example new language XY is published and I want to write snippets - prism does not support the language yet, but in few months it will. In case of throwing exception, I'd need to rewrite my old snippets to be properly highlighted, but if there's a fallback, I don't need to do anything apart from upgrading prism.

For a heading on GitHub, the anchor tag is only on the link image to the left of the heading. This can be seen in the gif below by the fact that the cursor is a pointer unless it hovers over the link image where it becomes a hand with the index finger extended. This makes it possible to select the heading and copy it (e.g. in the image below, that would be putting "GitHub" on the clipboard).

In contrast, for a site made with CODEDOC, the anchor tag spans the same width as the heading. This can be seen in the gif below by the fact that the cursor is a hand with the index finger extended the entire time that the link image is displayed. If I would have tried to select the heading for the purpose of copying it (i.e. to copy "Usage"), then the link to the heading would be put on the clipboard instead.

This behavior is particularly weird when the user wants to put their own anchor tag in the heading. Then clicking the heading first copies the link to the clipboard and then follows the link.

I prefer the way that heading anchors work on GitHub.

Can CODEDOC be changed to create headings with anchors like those on GitHub?

Found while checking my site with Chromes Lighthouse feature:

https://web.dev/doctype/?utm_source=lighthouse&utm_medium=devtools

The currently generated HTML lack <!DOCTYPE html>

The tab references example shows that the title is both the name of the tab displayed to the user as well as the identifier that is used to reference it from another tab.

What about splitting these two responsibilities into separate attributes (or whatever they are called)?

For example, it could look like this:

> :Tabs
> > :Tab name=Main Thing
> > ```ts
> > import { Stuff } from './other-thing';      // @see tab:other
> > import { MoreStuff } from './other-thing';  // @see [le source](tab:other)
> > ```
>
> > :Tab name=Other Thing id=other
> > ```ts
> > export const Stuff = 2;
> > export const MoreStuff = 3;                 // --> bet you expected more from this code sample didn't ya?
> > ```

The tooltip for // @see tab:other would still be See Other Thing because the default behavior would still be to display the name of the tab.

I see three advantages with this approach.

1. The existence of the id attribute communicates the intention in the source code that a tab is being referenced from other tab.
2. The name of the tab can be changed without needing (and possibility forgetting) to also change all the references.
3. The name of the tab might be long, but the ID could be very short, which can help improve readability.

There are warnings when I execute codedoc install and an error when I execute codedoc serve.

At the end of the executing various commands, I got the version information, which is

@codedoc/cli version 0.1.4 ...................................... latest: 0.1.4
@codedoc/core version: 0.1.62 ................................... latest: 0.1.62

Is there is anything else I can do to help fix this?

twilliams@EDMONDS MINGW64 /c/Code/Blogs/tyson-williams-blog (master)
$ codedoc install

# Installing local packages required by codedoc ...
npm WARN notice [SECURITY] set-value has the following vulnerability: 1 high. Go here for more details: https://www.npmjs.com/advisories?search=set-value&version=2.0.1 - Run `npm i npm@latest -g` to upgrade your npm version, and then `npm audit` to get more info.
npm WARN .codedoc No description
npm WARN .codedoc No repository field.
npm WARN .codedoc No license field.
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: [email protected] (node_modules\watchpack-chokidar2\node_modules\fsevents):
npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for [email protected]: wanted {"os":"darwin","arch":"any"} (current: {"os":"win32","arch":"x64"})
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: [email protected] (node_modules\fsevents):
npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for [email protected]: wanted {"os":"darwin","arch":"any"} (current: {"os":"win32","arch":"x64"})

added 574 packages in 18.347s


twilliams@EDMONDS MINGW64 /c/Code/Blogs/tyson-williams-blog (master)
$ codedoc serve

# Error: your local codedoc installation is incomplete.
# There are some packages missing from .codedoc/node_modules
# - Run codedoc install to install them.
# - Or run codedoc update to install the latest version.


twilliams@EDMONDS MINGW64 /c/Code/Blogs/tyson-williams-blog (master)
$ codedoc install

# Installing local packages required by codedoc ...
npm WARN [email protected] requires a peer of canvas@^2.5.0 but none is installed. You must install peer dependencies yourself.
npm WARN [email protected] requires a peer of typescript@* but none is installed. You must install peer dependencies yourself.
npm WARN [email protected] requires a peer of bufferutil@^4.0.1 but none is installed. You must install peer dependencies yourself.
npm WARN [email protected] requires a peer of utf-8-validate@^5.0.2 but none is installed. You must install peer dependencies yourself.
npm WARN .codedoc No description
npm WARN .codedoc No repository field.
npm WARN .codedoc No license field.
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: [email protected] (node_modules\fsevents):
npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for [email protected]: wanted {"os":"darwin","arch":"any"} (current: {"os":"win32","arch":"x64"})
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: [email protected] (node_modules\watchpack-chokidar2\node_modules\fsevents):
npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for [email protected]: wanted {"os":"darwin","arch":"any"} (current: {"os":"win32","arch":"x64"})

up to date in 2.868s


twilliams@EDMONDS MINGW64 /c/Code/Blogs/tyson-williams-blog (master)
$ codedoc update

# Updating CLI ...
# Updating local codedoc installation ...


twilliams@EDMONDS MINGW64 /c/Code/Blogs/tyson-williams-blog (master)
$ codedoc serve

# Error: your local codedoc installation is incomplete.
# There are some packages missing from .codedoc/node_modules
# - Run codedoc install to install them.
# - Or run codedoc update to install the latest version.


twilliams@EDMONDS MINGW64 /c/Code/Blogs/tyson-williams-blog (master)
$ codedoc install

# Installing local packages required by codedoc ...
npm WARN [email protected] requires a peer of canvas@^2.5.0 but none is installed. You must install peer dependencies yourself.
npm WARN [email protected] requires a peer of typescript@* but none is installed. You must install peer dependencies yourself.
npm WARN [email protected] requires a peer of bufferutil@^4.0.1 but none is installed. You must install peer dependencies yourself.
npm WARN [email protected] requires a peer of utf-8-validate@^5.0.2 but none is installed. You must install peer dependencies yourself.
npm WARN .codedoc No description
npm WARN .codedoc No repository field.
npm WARN .codedoc No license field.
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: [email protected] (node_modules\fsevents):
npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for [email protected]: wanted {"os":"darwin","arch":"any"} (current: {"os":"win32","arch":"x64"})
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: [email protected] (node_modules\watchpack-chokidar2\node_modules\fsevents):
npm WARN notsup SKIPPING OPTIONAL DEPENDENCY: Unsupported platform for [email protected]: wanted {"os":"darwin","arch":"any"} (current: {"os":"win32","arch":"x64"})

up to date in 2.724s


twilliams@EDMONDS MINGW64 /c/Code/Blogs/tyson-williams-blog (master)
$ codedoc serve

# Error: your local codedoc installation is incomplete.
# There are some packages missing from .codedoc/node_modules
# - Run codedoc install to install them.
# - Or run codedoc update to install the latest version.

twilliams@EDMONDS MINGW64 /c/Code/Blogs/tyson-williams-blog (master)
$ codedoc version

# Fetching version info ...
# @codedoc/cli version 0.1.4 ...................................... latest: 0.1.4
# @codedoc/core version: 0.1.62 ................................... latest: 0.1.62

I am not sure if it is a bug (if recursive watching is intended to work), but I believe such feature would be useful.

$ tree docs
docs
├── assets
│   ├── codedoc-bundle.entry.js
│   ├── codedoc-bundle.js
│   ├── codedoc-bundle.meta.json
│   └── codedoc-styles.css
├── dist
│   ├── api
│   │   └── index.html
│   ├── codedoc-bundle.entry.js
│   ├── codedoc-bundle.js
│   ├── codedoc-bundle.meta.json
│   ├── codedoc-styles.css
│   └── index.html
└── md
    ├── api
    │   └── index.md
    ├── index.md
    └── _toc.md

when I run codedoc serve, it doesn't pickup changes in docs/md/api/index.md (it detects changes in docs/md/index.md correctly).

It's possible I have it misconfigured, my config.ts (which works for serve and build, meaning it compiles and paths are correct):

import {configuration} from '@codedoc/core';

import {theme} from './theme';


export const config = /*#__PURE__*/configuration({
  theme,                                  // --> add the theme. modify `./theme.ts` for chaning the theme.

  page: {
    title: {
      base: 'Golden Gadget'               // --> the base title of your doc pages
    }
  },

  dest: {
    html: 'docs/dist',
    assets: 'docs/dist',
    bundle: '.',
    styles: '.',
    namespace: '/golden-gadget'
  }

});

I don't think I changed any other file (except index.tsx in content, but that should not be related, just the hamburger being opened by default).

If anyone encounters similar issue, here is my current workaround:

find docs/md | entr -r codedoc serve

Codedoc's code blocks are largely based on Marked (c.f. #25), but there are some differences (achieved via preprocessing).

Just like it is possible to demo Marked, is there a page where it is possible to demo codedoc's code blocks?

If the user provides a path to a favicon in the config...

...then CODEDOC adds the following link element...

...to the head element.

A web programmer friend of mine recommended RealFaviconGenerator. Maybe there are a hundred sites like this; I am still new to this.

For what it's worth though, RealFaviconGenerator thinks there are many opportunities for codedoc.cc to improve its use of favicons. Here is the report.

Given a master image (with size 260x260 or more), these instructions show how to use the npm package cli-real-favicon to generate all the various image files and then modify any HTML to correctly reference those images.

Is there any desire for CODEDOC to take this on as a dependency to step up its favicon game?

Or would it be more appropriate to make a plugin for CODEDOC that utilizes ReadFaviconGenerator?

I would like to be able to nest sidebar items at least one extra level. I don't think there is currently a way to do this but I might be wrong.

ie

toplevel/
  some-article
  sublevel/
     some-other-article

Since GitHub introduced this feature, I find myself constantly using it for referencing code. I suspect it will be exceedingly useful in CODEDOC as well to be able to reference specific parts of code snippets via permalinks. At least, some form of permalink per snippet seems like a basic necessity now. Perhaps both should be implemented?

I want to group my posts into a folder in my repository but have them accessible via URLs that do not contain "posts/".

Here is my attempt.

afterBuild: [
  function moveUpHtmlInPosts(build: Build<CodedocConfig>) {
    files('.')
      .pick(file => file.path.startsWith("dist\\posts\\"))
      .pipe(readFile(),
            mapPath(path => path.replace("dist\\posts\\", "dist\\")),
            writeFile())
      .process();
    files('.')
      .pick(file => file.path.startsWith("dist\\posts\\"))
      .pipe(deleteFile())
      .process();
  }
],

I got halfway there. The first part copies the generated HTML of the posts up one directory but second part doesn't delete any files...because deleteFile doesn't exist.

Since rxline/fs exported readFile and writeFile, I was hoping that it also exported deleteFile, but it does not.

How can I delete the files in dist/posts?

P.S.
Is this a good approach to move the HTML from dist/posts to dist?

when updating ToC, the new ToC is not loaded and used, so you can only get it when you manually kill the serve process and restart it.