Comments (6)
In setting up my projects here on GitHub I was unable to embed an image in a wiki topic. Looking at the example above for the class topic, this functionality does appear to be broken at the current time. The only workaround I was able to find is to host the wiki images externally either in the code repo or at a separate site altogether and use a fully qualified URL to show them. As such, it would seem necessary that any presentation style using a markdown format would need a project property to specify the root URL to add to all image references.
from shfb.
@EWSoftware Yes something is up with relative image paths. They are returned but as octet streams, so the browser won't display them. I've submitted a request to GitHub to get this fixed.
from shfb.
@EWSoftware Issue on GitHub has now been fixed. Here's an example page showing two working syntaxes: https://github.com/dotMorten/SandcastleMarkupDocTest/wiki/TestPage
Also here's an example page for members now displaying right: https://github.com/dotMorten/SandcastleMarkupDocTest/wiki/TestNamespace.StoredNumber%20Class
from shfb.
@dotMorten Thanks for the update and the example.
from shfb.
I've made a start on this and have a rough framework for the presentation style itself. I still need to integrate it into the build engine.
Limitations
The markdown generated is geared towards GitHub flavored markdown. Results may vary on other sites.
Code colorization is left to the markdown processor. The line numbering and collapsible region features of the code block component are not supported. Those features will be ignored.
Obviously, the language filter from the HTML help formats is not supported. As such, language-specific text will be shown using the generic, multi-language style. Likewise, syntax sections and code blocks are shown in a sequential fashion similar to the topic previewer.
Address anchors on elements such as list items and table cells are not supported as GitHub strips most attributes from elements. Links to title elements and the introduction should be supported.
"No Bullet" style lists and image placement options are not supported as GitHub strips the style attribute from all elements.
Literal HTML in conceptual topics and XML comments may not be rendered as expected since the markdown processor strips most attributes from the elements (id, style, etc.).
It isn't possible to check for and escape every possible markdown directive in conceptual topic text and XML comments text. As such, certain constructs may be interpreted as markdown and rendered differently. For example, if your comments contain the literal text "Some text surrounded by asterisks", it will most likely be rendered as emphasized text rather than literal text in asterisks as it would in website output.
Markdown processors make certain assumptions about various elements which do not always hold true for the content generated by the presentation style. In addition, certain HTML elements must be formatted very specifically to work around issues in the markdown processors. For example:
- Markdown table cells cannot span multiple lines.
- Markdown list items cannot contain multiple paragraphs.
- Markdown elements embedded within certain HTML elements (i.e. li elements) do not get processed.
- HTML tables must be followed by a non-breaking space or the markdown processor may ignore markdown elements within the cells.
As such, a lot more HTML is generated by the presentation style than you would see if it was written by hand to work around such limitations since the presentation style cannot assume the content fits the layout requirements expected by the markdown processors.
GitHub uses the filename as the page title. Topics will continue to use the selected naming method and, as such, you will see that filename at the topic of each page. The topic title rendered by the presentation style will appear below it. This may not be ideal but is necessary. The topic title cannot be used as the filename since they need to be unique across all topics documented. For example, if Class1 appeared in two separate namespaces and the topic titles were used as filenames, the topics from one of the classes would overwrite the other. Fully qualifying the names and including parameter information would allow them to be unique but would most likely result in extremely long filenames that could exceed the maximum filename length limit.
If these limitations are not acceptable, it is suggested the you generate the content as a website and host it somewhere such as the GitHub Pages site related to your project.
from shfb.
@EWSoftware Nice! This is awesome progress!
from shfb.
Related Issues (20)
- Nested `private protected` types incorrectly included in documentation HOT 2
- C# `init` property accessors documented as `set` HOT 3
- Please document methods parameters regardless syntax filters setup HOT 2
- BE0066: ResolveReferenceLinksComponent: [...] Member ID URL resolver service failed. HOT 5
- `See` element and override within sealed class HOT 2
- Easy to conflict with Microsoft.Help.F1 HOT 4
- autoOutline differences between Default2022 and VS2013 styles HOT 5
- [Question] My help file builds successfully but only has one namespace HOT 4
- Cannot install extension on arm64 HOT 1
- Enable TOC using current presentation style HOT 4
- TOC overlaying wide content HOT 4
- Building with NuGet tools with MsBuild is broken in Visual Studio HOT 4
- Numeric constant formatting for enumeration to allow searching for constant HOT 2
- Error BE0065: An error occurred while attempting to transform the reflection data to a topic. When Extensions Methods to Enum. HOT 3
- Some types excluded from documentation? HOT 3
- Documenting a `net8.0` project when using `msbuild.exe` HOT 3
- Linux/Docker builds HOT 5
- An error occurred while attempting to transform the reflection data to a topic. The error message was: System.NullReferenceException HOT 3
- Problem with installer when only VS 2022 is installed. HOT 4
- Support for Nuget Central Package Management
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from shfb.