Added Raw Block for User Formatted Text (#91)

* Added raw block

* Added tests

* Added docs

* Moved render to __str__ in doc

snakemd/generator.py

@@ -1115,11 +1115,30 @@ def verify(self):
                 verification.absorb(item.verify())
 
         return verification
-
+
+
+class Raw(Block):
+    """
+    Raw blocks allow a user to insert text into the Markdown
+    document without an processing. Use this block to insert
+    raw Markdown or other types of text (e.g., Jekyll frontmatter).
+    
+    .. versionadded:: 0.14.0
+    """
+    def __init__(self, text: str) -> None:
+        super().__init__()
+        self._text = text
+
+    def __str__(self) -> str:
+        return self._text
+
+    def verify(self) -> Verification:
+        return Verification()
+
 
 class TableOfContents(Element):
     """
-    A Table of Contents is an element containing an ordered list
+    A Table of Contents is an block containing an ordered list
     of all the `<h2>` headings in the document by default. A range can be
     specified to customize which headings (e.g., `<h3>`) are included in
     the table of contents. This element can be placed anywhere in the document.
@@ -1221,23 +1240,31 @@ class Document:
     def __init__(self, name: str = None) -> None:
         self._name: str = name
         self._ext: str = ".md"
-        self._contents: list[Element] = list()
+        self._contents: list[Block] = list()
         if name:
             warnings.warn(
                 "name parameter has been deprecated as of 0.13.0", 
                 DeprecationWarning
             )
 
     def __str__(self):
-        return self.render()
+        """
+        Renders the markdown document from a list of blocks.
+
+        :return: the document as a markdown string
+        """
+        return "\n\n".join(str(block) for block in self._contents)
 
     def render(self) -> str:
         """
         Renders the markdown document from a list of elements.
+        
+        .. deprecated:: 0.14.0
+            removed in favor of __str__
 
         :return: the document as a markdown string
         """
-        return "\n\n".join(str(element) for element in self._contents)
+        return str(self)
 
     def check_for_errors(self) -> None:
         """
@@ -1299,6 +1326,21 @@ def add_block(self, block: Block) -> Block:
         self._contents.append(block)
         logger.debug(f"Added block to document\n{block}")
         return block
+
+    def add_raw(self, text: str) -> Raw:
+        """
+        A convenience method which adds text as-is to the document:
+        
+        .. code-block:: Python
+
+            doc.add_raw("X: 5\nY: 4\nZ: 3")
+
+        :param str text: some text 
+        :return: the Raw block added to this Document
+        """
+        raw = Raw(text)
+        self._contents.append(raw)
+        return raw
 
     def add_heading(self, text: str, level: int = 1) -> Heading:
         """

tests/test_raw.py

@@ -0,0 +1,18 @@
+from snakemd import Raw
+
+
+def test_raw_empty():
+    raw = Raw("")
+    assert str(raw) == ""
+
+def test_raw_one_line():
+    raw = Raw("Hello, World!")
+    assert str(raw) == "Hello, World!"
+
+def test_raw_two_lines():
+    raw = Raw("Hello,\nWorld!")
+    assert str(raw) == "Hello,\nWorld!"
+
+def test_raw_user_example():
+    raw = Raw("Title: My super title\nDate: 2010-12-03 10:20")
+    assert str(raw) == "Title: My super title\nDate: 2010-12-03 10:20"