Support optional includes for page fragments

[Xenonym]

What is the purpose of this pull request? (put "X" next to an item, remove the rest)
• [X] Enhancement to an existing feature

Resolves #497.

What is the rationale for this request?
Currently, we allow optional inclusion of whole documents with the optional tag eg.
<include src="doc.md" optional />. This PR extends this functionality to page fragments as well eg.
<include src="doc.md#segment" optional /> will be included only if #segment exists.

What changes did you make? (Give an overview)
When a page fragment that is included does not exist, we check first if the optional tag is used. If so, we include an empty string in place, leading to an empty <div>. If not, an error is emitted that the page fragment included does not exist.

Provide some example code that this change will affect:

<include src="doc.md#exists" optional />
<include src="doc.md#doesNotExist" optional />
<include src="doc.md#doesNotExist" />

Is there anything you'd like reviewers to focus on?
In previous versions, inclusion of nonexistent page fragments lead to a <div> with the string null being included instead. Since this behavior is likely to be confusing with the addition of optional, I have chosen to change this so that an error is emitted when an included page fragment does not exist and optional was not used. I have also added tests to verify this new behavior alongside those that verify the behavior of optional with page fragments.

Testing instructions:

1. Include a page fragment with optional eg. <include src="doc.md#exists" optional />. The content of the page fragment should be included.
2. Include a nonexistent page fragment with optional eg.
   <include src="doc.md#doesNotExist" optional />. There should not be an error and the page should render as normal.
3. Include a nonexistent page fragment normally eg. <include src="doc.md#doesNotExist" />. An error should be emitted.

[yamgent]

Ok, just a minor nit in error message:

[damithc]

This probably needs a slight update to docs?

[yamgent]

This probably needs a slight update to docs?

Hmm, it didn't cross my mind for this feature, as we do not explicitly mention that other attributes such as inline and trim works for fragments as well in the current documentation, because it seems to be implied.

Although I agree that a minor mention might make it clearer and more obvious for the author. Maybe such a mention will work?

diff --git a/docs/userGuide/reusingContents.md b/docs/userGuide/reusingContents.md
index e9e957a..15dea5b 100644
--- a/docs/userGuide/reusingContents.md
+++ b/docs/userGuide/reusingContents.md
@@ -186,14 +186,14 @@ Attributes:
   <include src="frament.md" trim />
   \```
 
-**You can `<include>` a fragment of a file** by specifying the `#fragment-id` at the end of the `src` attribute value, provided the fragment is wrapped in a `<div>`/`<span>`/`<seg>` tag with the matching `id`.
+**You can `<include>` a fragment of a file** by specifying the `#fragment-id` at the end of the `src` attribute value, provided the fragment is wrapped in a `<div>`/`<span>`/`<seg>` tag with the matching `id`. You can use the attributes for documents (such as `inline` and `optional`) with fragments as well.
 
 <div class="indented">
 
 {{ icon_example }} Including a fragment from a file:
 \```html
 Some text
-<include src="docs/tips.md#tip-1" />
+<include src="docs/tips.md#tip-1" trim />
 Some other text
 \```

[damithc]

Yes, it is awkward to mention it in the current doc. The problem is, fragment inclusion is mention after the attributes. Let's leave it be.