We sometimes see UTF-8 quotes in code elements like

YYYY-MM-DD open Account [ConstraintCurrency,...] [“BookingMethod”]

Since this is invalid, I am wondering if the conversion should fix that.

(I'll try to fix the Google docs as well.)

This list under "Tags" at https://xuhcc.github.io/beancount-docs/24_beancount_design_doc.html (search for "Tags are sets of strings that can be used to group sets of") is split into two lists:

<li>All transactions during a particular travel might be tagged to later summarize your trip expenses. Those transactions will usually occur around the same date and therefore there is convenient syntax used to automatically tag many transactions that are declared together in a file.</li>
</ul>
<!-- -->
<ul>
<li>

Looking at the Google doc is looks like a single list. Is this a problem with the conversion or the Google doc?

In the Google docs quotes are often used around text which uses Consolas font. On the Google docs this looks fine. But on the converted docs, this looks odd because of the way code is highlighted. I therefore suggest to strip quotes around text that is completely Consolas.

An example is here: https://xuhcc.github.io/beancount-docs/01_command_line_accounting_in_context.html

The CAFE MOGADOR NEW YO bit is the

I think it makes sense to make this change as part of the Markdown conversion simply because these code elements are displayed differently to Google Docs and so it doesn't make sense to change the original document.

(This is different to issue #7)

These docs are wonderful, an by far my preferred method of finding beancount info. However, I would love to see a Search functionality (similar to what is on aumayr's doc page). The categorization in beancount's documentation is not always obvious and being able to find the proper section without going back to google would be nice (especially since Google has apparently not yet indexed the new doc location)

Maybe I'm wrong but it seems that font "consolas" should always be converted to Markdown code.

For example at https://docs.google.com/document/d/1s0GOZMcrKKCLlP29MD7kHO4L88evrwWdIO0p4EwRBE0/ we have:

Null objects (NULL)

NULL is in consolas font. And in fact: Null objects (NULL) looks better to me.

Is there a reason this is not done? Maybe there's a good reason.

I forked your project here, it is awesome, just having access to the docs as markdown is a big win for me. I noted the jekyll site, and wondered if mkdocs could improve the experience. I realize there is an attempt to use Sphinx, I'm not sure if they can improve beyond current implementation. If I understand correctly, one limitation of readthedocs theme is, it's limited to depth two. Not sure if that is relevant here. I have a prototype of a MkDocs version of your site, at https://bradyt.github.io/beancount-docs/. I suspect it would be trivial to add an "edit page" button. I'm not sure yet how to fix rendering of in-page table of contents into left pane (or top of page for narrow screens). I'm not sure yet how to fix the linking of images.

(I had some errors running crawl.py, but hoping to ignore that until I really have to spend time on it.)

I wanted to make a (small) edit to https://beancount.github.io/docs/external_contributions.html (to add the full list of the existing importers of @tarioch https://github.com/tarioch/beancounttools), and figured this Git repo is the source of that site.

It's just not clear (to me) yet, neither from the README nor the CONTRIBUTING, how one may raise a PR or suggest an edit - in whatever form the maintainers of this (amazing) community prefer.

CONTRIBUTING says to check this thread which I have glanced over but still not understood how to.

Perhaps this could be clarified; I'm happy to raise a PR if when I learn how you like contribs.

@bradyt @xuhcc

beancount-docs uses pandoc to convert between exported docx documents and markdown. Versions of pandoc greater than 2.7.2 have a bug which prevents them from converting documents correctly (see jgm/pandoc#5971) so we can not use them. Package py-pandoc was used to easily install pandoc 2.7.2 with pip but it fails to install on python 3.10 (it failed on 3.9 too but maintainer agreed to publish a new version kiwi0fruit/py-pandoc#4).

The link in the footnote at the end of the intro refers to the .md extension instead of .html

It would be nice to generate a PDF.

It seems there are several options to generate PDFs, including:

https://github.com/zhaoterryy/mkdocs-pdf-export-plugin

https://github.com/comwes/mkpdfs-mkdocs-plugin

https://xuhcc.github.io/beancount-docs/06_beancount_language_syntax.html says

For a deeper discussion of how and when to use payees or not, see Payees, Subaccounts, and Assets.

Also:

Same for "There is a proposal pending to allowing"

Both are links to Same for furius.ca. Any reason these aren't converted?

Hi, I was trying to build locally, but after pip3 install -r requirements.txt, I get the following.

$ python3 crawl.py 
Found 32 documents
Processing https://docs.google.com/document/d/1RaondTJCS_IUPBHFNdT8oqFKJjVJDsfsn6JEjBG04eA/
Traceback (most recent call last):
  File "crawl.py", line 65, in <module>
    main()
  File "crawl.py", line 59, in main
    convert(document, output_path)
  File "/Users/alice/code/beancount-docs/export.py", line 125, in convert
    outputfile=output,
  File "/usr/local/lib/python3.7/site-packages/pypandoc/__init__.py", line 103, in convert_text
    outputfile=outputfile, filters=filters)
  File "/usr/local/lib/python3.7/site-packages/pypandoc/__init__.py", line 325, in _convert_input
    'Pandoc died with exitcode "%s" during conversion: %s' % (p.returncode, stderr)
RuntimeError: Pandoc died with exitcode "83" during conversion: b'  File "filter.py", line 39\n    def resolve_url(url: str) -> str:\n                       ^\nSyntaxError: invalid syntax\nError running filter filter.py:\nFilter returned error status 1\n'

For some reason mkdocstrings fails to generate documentation for beancount.tools:

Traceback (most recent call last):
  File "/venv/lib/python3.8/site-packages/pytkdocs/cli.py", line 179, in main
    print(json.dumps(process_json(line)))
  File "/venv/lib/python3.8/site-packages/pytkdocs/cli.py", line 116, in process_json
    return process_config(json.loads(json_input))
  File "/venv/lib/python3.8/site-packages/pytkdocs/cli.py", line 93, in process_config
    obj = loader.get_object_documentation(path, members)
  File "/venv/lib/python3.8/site-packages/pytkdocs/loader.py", line 210, in get_object_documentation
    root_object = self.get_module_documentation(leaf, members)
  File "/venv/lib/python3.8/site-packages/pytkdocs/loader.py", line 297, in get_module_documentation
    leaf = get_object_tree(f"{path}.{modname}")
  File "/venv/lib/python3.8/site-packages/pytkdocs/loader.py", line 146, in get_object_tree
    obj = getattr(current_node.obj, obj_name)
AttributeError: module 'beancount.tools' has no attribute 'sheets_upload'

Is there a way to trigger the regeneration of the documentation or is it a manual process?

The manual has stuff like:

characters with the “-w” option.
“--render-balance”

I wonder if everything that looks like an an argument (i.e. something like ^-[\w-]) should be converted to `code`.

Other things that might be converted like this:

• single characters: e.g.

Tags must begin with “#”, and links with “^”.

• maybe dates: \d\d[./]\d\d[./]\d\d

The first paragraph of text after the first code block in this section https://beancount.github.io/docs/getting_started_with_beancount.html#emacs get incorrectly included in the code block. I don't see anything obviusly wrong with the Google Docs document. How can I fix this?

The formatting is off. It appears to be a combination of the indentation being lost and the paragraphs not being formatted like the source.

https://docs.google.com/document/d/1_-T_BvDtUjj9M7liZMNSkrL8pgC60TGMBlYCiV1e4ZM/edit

And the output:

If configurable in pandoc, an option would be to use a definition-list, DL.
In the current theme, the following HTML:

<dl>
  <dt>option “account_previous_balances” “Opening-Balances"</dt>
  <dd>Leaf name of the equity account used for summarizing previous 
transactions into opening balances.</dd>
</dl>

Shows up as:

• Update repo url in documentation: https://docs.google.com/document/d/1Z37bQ45wDtjTPaMQ_x-f33p1trH9fNosEAUgbQXwp30/edit#heading=h.wcyqutvazcon
• Update url in repo description.
• Update awesome-beancount.
• Update https://plaintextaccounting.org/#general-accounting

It seems multi-line code paragraphs were broken by commit 0091d1b.

For example:

-    import beancount.loader  
-    …  
-    entries, errors, options = beancount.loader.load\_file(‘myfile.ledger’)  
-    for entry in entries:  
-    …
+    `import beancount.loader … entries, errors, options = beancount.loader.load_file(‘myfile.ledger’) for entry in entries: …`

-    **easy\_install-3.4 pip  
-    **Make sure you invoke the version of easy\_install which matches your Python version, e.g. easy\_install-3.5 if you have Python 3.5 installed, or more.
+    **`easy_install-3.4 pip `**Make sure you invoke the version of easy\_install which matches your Python version, e.g. easy\_install-3.5 if you have Python
 3.5 installed, or more.

-    2015-11-20 price ITOT    95.46 USD
-    2015-11-20 price LQD    115.63 USD
-    2015-11-21 price USD   1.33495 CAD
-    …
+`2015-11-20 price ITOT 95.46 USD 2015-11-20 price LQD 115.63 USD 2015-11-21 price USD 1.33495 CAD …`