diff --git a/flexmark-java-samples/src/com/vladsch/flexmark/java/samples/JekyllIncludeFileSample.java b/flexmark-java-samples/src/com/vladsch/flexmark/java/samples/JekyllIncludeFileSample.java
index 032f33766..5906f63a3 100644
--- a/flexmark-java-samples/src/com/vladsch/flexmark/java/samples/JekyllIncludeFileSample.java
+++ b/flexmark-java-samples/src/com/vladsch/flexmark/java/samples/JekyllIncludeFileSample.java
@@ -11,6 +11,15 @@
 
 import java.util.*;
 
+/**
+ * This sample uses the parsed document to compute the embedded content. 
+ * 
+ * This means that the main document is parsed twice. 
+ * 
+ * For a sample which can compute the embedded content without needing to examine
+ * the main document AST and therefore, computes the content map before parsing 
+ * the main document, see: {@link JekyllIncludeFileSample2}
+ */
 public class JekyllIncludeFileSample {
     static String commonMark(String markdown, Map<String, String> included) {
         MutableDataHolder options = new MutableDataSet();
diff --git a/flexmark-java-samples/src/com/vladsch/flexmark/java/samples/JekyllIncludeFileSample2.java b/flexmark-java-samples/src/com/vladsch/flexmark/java/samples/JekyllIncludeFileSample2.java
index 6e0386acb..922a38a0c 100644
--- a/flexmark-java-samples/src/com/vladsch/flexmark/java/samples/JekyllIncludeFileSample2.java
+++ b/flexmark-java-samples/src/com/vladsch/flexmark/java/samples/JekyllIncludeFileSample2.java
@@ -13,6 +13,15 @@
 import java.util.HashMap;
 import java.util.Map;
 
+/**
+ * This sample computes the html content map without examining the main document AST.
+ *
+ * This means that the main document is parsed once. 
+ *
+ * For a sample which needs to examine the document AST include tags to compute 
+ * the embedded content map, which results in the main document being parsed twice,
+ * see: {@link JekyllIncludeFileSample}
+ */
 public class JekyllIncludeFileSample2 {
     static String commonMark(String markdown, Map<String, String> included) {
         MutableDataHolder options = new MutableDataSet();