Skip to content

Commit 044411b

Browse files
EWSoftwareEWSoftware
committed
Updates for release
- Minor fixes to Markdown conceptual content support. - Added quick info tooltips and Go to Definition support to Markdown topics. - Updated documentation for release.
1 parent c16ac79 commit 044411b

File tree

76 files changed

+3600
-3132
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

76 files changed

+3600
-3132
lines changed

‎Deployment/InstallerConfiguration.xml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<?xml version="1.0" encoding="utf-8" ?>
22
<configuration>
33
<!-- This indicates the tools version with which this installer is associated.-->
4-
<tools version="2025.9.30.0" />
4+
<tools version="2025.12.18.0" />
55

66
<!-- Define the installer pages. Third-party build tool and component providers can add new pages that
77
they have created to install their own products as well. -->
@@ -13,7 +13,7 @@
1313
<page type="Sandcastle.Installer.InstallerPages.WelcomePage" />
1414

1515
<page type="Sandcastle.Installer.InstallerPages.WhatsNewPage">
16-
<whatsNew url="https://EWSoftware.github.io/SHFB/html/45d01e39-8086-4e10-85e6-69591d26a032.htm"
16+
<whatsNew url="https://EWSoftware.github.io/SHFB/html/v2025.12.18.0.htm"
1717
description="Current Version Release Notes" />
1818
<whatsNew url="https://EWSoftware.github.io/SHFB/html/bc933f8f-e792-45bf-afec-62aa2c46aa3b.htm"
1919
description="Third-Party Component Migration Support" />

‎Documentation/SandcastleBuilder/CommonTokens.tokens‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,6 @@
66
<ddue:linkUri>https://GitHub.com/EWSoftware/SHFB</ddue:linkUri>
77
<ddue:linkTarget>_blank</ddue:linkTarget>
88
</ddue:externalLink></item>
9-
<item id="SandcastleVersion">v2025.9.30.0</item>
9+
<item id="SandcastleVersion">v2025.12.18.0</item>
1010
<item id="VisualStudioMinVersion">Visual Studio 2022</item>
1111
</content>

‎Documentation/SandcastleBuilder/Content/AddConceptContent/AddConceptContent.aml‎

Lines changed: 0 additions & 47 deletions
This file was deleted.

‎Documentation/SandcastleBuilder/Content/AddConceptContent/AddConceptContent.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
uid: 5292ce5c-fda1-4a77-9155-a11755ef1730
3+
alt-uid: AddConceptContent
4+
title: Conceptual and Additional Content
5+
keywords: "additional content, general overview", "conceptual content, general overview"
6+
---
7+
In versions of the help file builder prior to version 1.7.0.0, the additional content properties were used to add
8+
files to the project to define additional help content that would appear in the table of contents and to add
9+
other items such as image files and additional style sheets. As an alternative to basic HTML files, you could
10+
also create XML files with a *.topic* extension that would be ran through an XSL transformation to give them the
11+
basic look and feel of the presentation style that was selected. However, using the basic transformations, the
12+
topics lacked several features present in the reference content such as collapsible sections and the language
13+
filter and they could not take advantage of build components to resolve links to reference and online content.
14+
15+
Starting with version 1.7.0.0, the help file builder supported conceptual content. This is similar in nature to
16+
additional content in that it allows you to add non-reference content to the help file that will appear in the
17+
table of contents. However, instead of HTML files or *.topic* files that contained HTML, conceptual content used
18+
topic files that contained Microsoft Assistance Markup Language (MAML). This is basically XML conforming to a
19+
well defined schema that describes the structure of the conceptual content much like XML comments describe the
20+
structure of the code comments.
21+
22+
Starting with version 2025.12.18.0, the help file builder supports using Markdown files in place of MAML. This
23+
allows for editing topics in a much easier manner and allows mixing in HTML and/or MAML elements as needed when
24+
Markdown doesn't provide the needed capabilities. Since most people are more familiar with Markdown than MAML,
25+
this is now the preferred approach and is the default topic format for all new projects going forward.
26+
27+
There is no layout or style information within the Markdown or MAML topic files. Instead, they are ran through a
28+
presentation style transformation using Sandcastle's **BuildAssembler** tool similar to the reference (API)
29+
content so that they match it in appearance and features. Whether you use Markdown or MAML, the presentation
30+
style transformations are responsible for applying the style and formatting of the rendered topics that appear in
31+
the help file. The look of the conceptual topics is much more consistent with that of the reference topics. As
32+
such, preference has been given to conceptual content when adding features to the help file builder. Support for
33+
the older additional content model has been reduced to simple inclusion of the files.
34+
35+
## See Also
36+
**Other Resources**
37+
[](@3d4edd2d-7883-4508-b9d2-bd7b4d848b0d)
38+
[](@ba42b2c2-985d-46f1-ba4c-3d921edcafe3)
39+
[](@4fd3b2b6-dfad-4513-983b-5e74d2342ff0)
40+
[](@MarkdownSupport)
41+
[](@ConvertingToMarkdown)

‎Documentation/SandcastleBuilder/Content/AddConceptContent/ConceptContent/ConceptContent.aml‎

Lines changed: 0 additions & 102 deletions
This file was deleted.

‎Documentation/SandcastleBuilder/Content/AddConceptContent/ConceptContent/ConceptContent.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
uid: 3d4edd2d-7883-4508-b9d2-bd7b4d848b0d
3+
alt-uid: ConceptContent
4+
title: Conceptual Content
5+
keywords: "conceptual content, overview"
6+
---
7+
Conceptual content is similar in nature to the additional content used in the help file builder prior to version
8+
1.7.0.0. It allows you to define non-API documentation that is included in the help file for usage notes,
9+
walkthroughs, tutorials, etc. Instead of HTML, conceptual content topics use Markdown or Microsoft Assistance
10+
Markup Language (MAML). There is no layout or style information within the Markdown or MAML files. Instead, they
11+
are ran through a presentation style transformation using Sandcastle's **BuildAssembler** tool similar to the
12+
reference (API) content so that they match it in appearance and features. This allows you to utilize the various
13+
build components to alter and extend the presentation style of the topics.
14+
15+
> [!TIP]
16+
> Starting with version 2025.12.18.0, Markdown is the preferred conceptual topic format. An option to convert
17+
> MAML topics to Markdown is available in the [](@54e3dc97-5125-441e-8e84-7f9303e95f26).
18+
>
19+
> A guide to using MAML with Sandcastle is
20+
> [available online](https://EWSoftware.GitHub.io/MAMLGuide "Sandcastle MAML Guide"). If you need to convert
21+
> older HTML topics to MAML topics, the
22+
> [HTML to MAML Converter](https://EWSoftware.GitHub.io/HtmlToMamlDocs "HTML to MAML Converter") is available
23+
> to help you.
24+
25+
## Conceptual Content Files
26+
Conceptual content is composed of several different file types within a project. You can use folders within the
27+
project to group these files as you see fit.
28+
29+
- [Content layout files](@54e3dc97-5125-441e-8e84-7f9303e95f26) define which topics are included in the help file
30+
and how they are arranged in the help file's table of contents. Content layout files have a `BuildAction` of
31+
`ContentLayout`.
32+
- [Topic files](@4b8ab701-2321-4d24-a287-8848de086f68) contain the Markdown or MAML that defines each topic.
33+
These files should have a `BuildAction` of `None`. The build process handles converting the topics to HTML
34+
and adding them to the help file based on a content layout file.
35+
- [Image files](@c38461a6-6edd-42cf-9d91-73c4b11cdd70#Image) define image resources used in the conceptual
36+
content. These have a `BuildAction` of `Image`.
37+
- [Token files](@ed6870bb-772d-4596-9fc1-5638ae6d621b) allow the definition of common Markdown or MAML snippets
38+
or content used in topic files. These have a `BuildAction` of `Tokens`.
39+
- [Code snippets files](@c38461a6-6edd-42cf-9d91-73c4b11cdd70#CodeSnippets) allow you to define code snippets
40+
that will be used in conceptual content topics and are rendered by Sandcastle's `ExampleComponent`. These
41+
have a `BuildAction` of `CodeSnippets`. See the MAML Guide for more information on creating code snippets
42+
files. These are rarely used anymore, if ever, since code blocks defined within the Markdown or MAML topics
43+
are capable of importing code snippets directly from source code files.
44+
45+
## Custom Template Files
46+
In the standalone GUI, the designer uses template files to create new conceptual topics. You can create your own
47+
templates for use in the designer by creating a *Conceptual Templates* folder in the **Local Application Data**
48+
folder. Any Markdown (*\*.md*) or MAML (*\*.aml*) files found in this folder will be added to the **Custom
49+
Templates** menu option in the **Add Sibling Topic** and **Add Child Topic** submenus. See the
50+
[](@a24489fb-45d6-46f4-9eaa-9a9c4e0919b2#FileTemplates) topic for more information.
51+
52+
See the [](@ece3a395-589f-45c3-9f0e-2a25b8b6c537) topic for information on creating file templates for use with
53+
content layout file editor in the Visual Studio package.
54+
55+
## See Also
56+
**Other Resources**
57+
[](@5292ce5c-fda1-4a77-9155-a11755ef1730)

0 commit comments

Comments
 (0)